canopycms 0.0.68-int.100 → 0.0.68-int.102

package/README.md

@@ -396,7 +396,7 @@ The editor loads entries on the client from `/api/canopycms/[branch]/entries`, s
 _TODO_ show an example
 
 7. **Split builds**
-   Keep your public build free of editor bundles by importing only from `canopycms` (server helpers + data loaders). Host the editor in a separate app or build target that imports from `canopycms/client` and mounts the API routes above.
+   Keep your public build free of editor bundles by importing only from `canopycms` (server helpers + data loaders) and `canopycms/preview` (the live-preview hook). Host the editor in a separate app or build target that imports from `canopycms/client` and mounts the API routes above.
 
 _TODO_ show real examples of what to do
 
@@ -415,7 +415,7 @@ The `useCanopyPreview` hook provides live updates to your preview components as
 ```tsx
 'use client'
 
-import { useCanopyPreview } from 'canopycms/client'
+import { useCanopyPreview } from 'canopycms/preview'
 import type { PostContent } from './schemas'
 
 export function PostView({ data }: { data: PostContent }) {
@@ -451,7 +451,7 @@ When using reference fields (foreign key relationships to other content), the ed
 ```tsx
 'use client'
 
-import { useCanopyPreview } from 'canopycms/client'
+import { useCanopyPreview } from 'canopycms/preview'
 
 export function PostView({ data }: { data: PostContent }) {
   const { data: liveData, isLoading } = useCanopyPreview<PostContent>({

package/dist/api/branch.js

@@ -14,6 +14,7 @@ import { filePathExists } from '../utils/fs.js';
 import { isNetworkRemoteUrl } from '../utils/git.js';
 import { sanitizeBranchName, RESERVED_SETTINGS_BRANCH_PREFIX, RESERVED_ROUTE_BRANCH_NAMES, isSettingsBranchName, } from '../paths/index.js';
 import { GitManager } from '../git-manager.js';
+import { syncDeleteRemoteBranch } from './github-sync.js';
 import { branchNameSchema, branchParamSchema } from './validators.js';
 const log = createDebugLogger({ prefix: 'BranchAPI' });
 const createBranchBodySchema = z.object({
@@ -568,6 +569,12 @@ export const deleteBranchHandler = async (ctx, req, params) => {
             console.warn(`CanopyCMS: failed to remove deleted branch's mirror head (branch ${sanitizedDeleted}, mirror ${mirrorPath}): ${getErrorMessage(err)}`);
         }
     }
+    // `branchContext` was read before the delete, so it still carries the PR number this gates on.
+    if (deletableHead) {
+        const warning = await syncDeleteRemoteBranch(ctx, branchContext);
+        if (warning)
+            cleanupWarning = cleanupWarning ? `${cleanupWarning}; ${warning}` : warning;
+    }
     // Invalidate registry cache so next list() will regenerate without this branch
     if (!ctx.services.registry) {
         return {

package/dist/api/client.d.ts

@@ -32,7 +32,8 @@ export interface ApiClientOptions {
      */
     trailingSlash?: boolean;
     /**
-     * Called whenever a response comes back 401: the credential is no longer accepted. A
+     * Called whenever a response says the credential is no longer accepted: HTTP 401, or a
+     * handler's body with `status: 401` under the HTTP status `unauthenticatedStatus` chose. A
      * notification, not a retry; the editor's auth gate uses it to show sign-in.
      */
     onUnauthorized?: () => void;

package/dist/api/client.js

@@ -341,7 +341,8 @@ export class CanopyApiClient {
             response = await this.fetchFn(url, init);
             parsed = await response.json().catch(() => undefined);
         }
-        if (response.status === 401) {
+        // The body's status is the signal: `unauthenticatedStatus` may send it under HTTP 419.
+        if (response.status === 401 || (isApiResponseBody(parsed) && parsed.status === 401)) {
             this.onUnauthorized?.();
             return { ok: false, status: 401, error: errorFromBody(parsed) ?? 'Unauthorized' };
         }

package/dist/api/github-sync.d.ts

@@ -26,3 +26,12 @@ export declare function syncSubmitPr(ctx: ApiContext, context: BranchContext, su
  * available, otherwise queues a task.
  */
 export declare function syncConvertToDraft(ctx: ApiContext, context: BranchContext): Promise<void>;
+/**
+ * Used by delete, after the local delete succeeded. Deletes the branch on GitHub when the CMS
+ * put it there: a content branch reaches GitHub only through submit, which always opens a PR,
+ * so a recorded PR number is the proof. Without one, a same-named GitHub branch is someone
+ * else's (the create-time collision check is best-effort) and is never touched.
+ *
+ * Returns a client-facing warning when the delete could not be done or queued; never throws.
+ */
+export declare function syncDeleteRemoteBranch(ctx: ApiContext, context: BranchContext): Promise<string | undefined>;

package/dist/api/github-sync.js

@@ -4,6 +4,7 @@ import { clientOperatingStrategy } from '../operating-mode/index.js';
 import { getErrorMessage } from '../utils/error.js';
 import { sanitizeBranchName } from '../paths/branch-name.js';
 import { buildPrSection, mergePrSection } from '../submission-attribution.js';
+import { isRefAlreadyGoneError } from '../github-service.js';
 /**
  * Uses githubService directly if available, otherwise queues a task for the worker.
  *
@@ -156,6 +157,42 @@ export async function syncConvertToDraft(ctx, context) {
         });
     }
 }
+/**
+ * Used by delete, after the local delete succeeded. Deletes the branch on GitHub when the CMS
+ * put it there: a content branch reaches GitHub only through submit, which always opens a PR,
+ * so a recorded PR number is the proof. Without one, a same-named GitHub branch is someone
+ * else's (the create-time collision check is best-effort) and is never touched.
+ *
+ * Returns a client-facing warning when the delete could not be done or queued; never throws.
+ */
+export async function syncDeleteRemoteBranch(ctx, context) {
+    if (!context.branch.pullRequestNumber)
+        return undefined;
+    const { githubService } = ctx.services;
+    const branch = context.branch.name;
+    if (githubService) {
+        try {
+            await githubService.deleteBranch(branch);
+        }
+        catch (err) {
+            if (isRefAlreadyGoneError(err))
+                return undefined;
+            console.error(`CanopyCMS: Failed to delete GitHub branch for ${branch}:`, getErrorMessage(err));
+            return 'The branch could not be deleted on GitHub; delete it there by hand';
+        }
+        return undefined;
+    }
+    const mode = ctx.services.config.mode;
+    if (!clientOperatingStrategy(mode).supportsPullRequests())
+        return undefined;
+    const result = await enqueueGitHubTask(ctx, context, {
+        action: 'delete-remote-branch',
+        payload: { branch, pullRequestNumber: context.branch.pullRequestNumber },
+    });
+    return result.syncStatus === 'sync-failed'
+        ? 'Deleting the branch on GitHub could not be queued; delete it there by hand'
+        : undefined;
+}
 async function enqueueGitHubTask(ctx, context, task) {
     const taskDir = getTaskQueueDir(ctx.services.config);
     try {

package/dist/assets/finalize.js

@@ -39,6 +39,9 @@ export async function finalizeAsset(store, input) {
     const existing = await store.getMeta(meta.hash32);
     if (existing)
         return { ok: true, meta: existing };
+    // Either put may find its key taken (`already-exists`): by an earlier attempt that stopped
+    // before the meta commit, or by a concurrent identical upload. The object kept there is this
+    // content's, so finalize goes on to commit the meta either way.
     await store.putOriginal({ hash32: meta.hash32, ext: meta.ext, data, contentType: meta.mime });
     if (publicObject) {
         await store.putPublicObject(publicObject);

package/dist/assets/materialize.d.ts

@@ -6,7 +6,7 @@
  * before that build is released) and canopycms-cdk's lazy transform Lambda.
  */
 import { type ParsedTransformPath } from './transform-directives.js';
-import type { AssetStore } from './types.js';
+import type { AssetStore, CreateOnlyResult } from './types.js';
 /** Every transform output is stored under a content-addressed key, so it never changes. */
 export declare const TRANSFORM_CACHE_CONTROL = "public, max-age=31536000, immutable";
 /**
@@ -19,26 +19,32 @@ export declare const LAZY_TRANSFORM_TAG: {
     readonly key: "canopy-transform";
     readonly value: "lazy";
 };
+/**
+ * `data` is the computed output whether or not it was stored: `stored: 'already-exists'` means
+ * another writer stored the key first, and the store kept that object.
+ */
 export type StoreTransformResult = {
     ok: true;
     data: Uint8Array;
     contentType: string;
+    stored: CreateOnlyResult;
 } | {
     ok: false;
     status: 400 | 404 | 413 | 422;
     error: string;
 };
 /**
- * Compute the transform `parsed` names from the asset's original and write it under
- * `canonicalKey`. `parsed` must come from `canonicalizeTransformPath`, so the stored pixels
- * always match their key. A rejection is a fact about the asset or the URL and is never worth
- * retrying; a thrown error belongs to the store or the environment. A 404's `error` names what
- * was missing, so a caller answering a browser replaces it.
+ * Compute the transform `parsed` names from the asset's original and write it under `key`: the
+ * canonical key, or that key beneath an output prefix. `parsed` must come from
+ * `canonicalizeTransformPath`, so the stored pixels always match their key. A rejection is a fact
+ * about the asset or the URL and is never worth retrying; a thrown error belongs to the store or
+ * the environment. A 404's `error` names what was missing, so a caller answering a browser
+ * replaces it.
  */
-export declare function storeTransform(store: AssetStore, parsed: ParsedTransformPath, canonicalKey: string, options?: {
+export declare function storeTransform(store: AssetStore, parsed: ParsedTransformPath, key: string, options?: {
     tags?: Readonly<Record<string, string>>;
 }): Promise<StoreTransformResult>;
-/** @internal One key a build references, and where it was referenced, for the failure report. */
+/** One key a build references, and where it was referenced, for the failure report. */
 export interface MaterializeTarget {
     /** `assets/t/{directives}/{hash32}/{slug}.{ext}`. */
     key: string;
@@ -56,17 +62,24 @@ export type MaterializeResult = {
     routes: string[];
     files: string[];
 } & ({
-    status: 'existed' | 'created';
+    status: 'existed' | 'created' | 'copied';
 } | {
     status: 'failed';
     failure: MaterializeFailureKind;
     error: string;
 });
+/** The `schemaVersion` of every `MaterializeReport`; a consumer gating on the JSON checks it. */
+export declare const MATERIALIZE_REPORT_SCHEMA_VERSION = 1;
 export interface MaterializeReport {
+    schemaVersion: typeof MATERIALIZE_REPORT_SCHEMA_VERSION;
+    /** `MaterializeOptions.outputPrefix`, present only when one was given. */
+    outputPrefix?: string;
     summary: {
         total: number;
         existed: number;
         created: number;
+        /** Keys copied from the canonical prefix into an output prefix; 0 until one is configured. */
+        copied: number;
         failed: number;
         contentFailures: number;
         storeFailures: number;
@@ -78,11 +91,18 @@ export interface MaterializeOptions {
     store: AssetStore;
     targets: readonly MaterializeTarget[];
     /**
-     * `assets/{hash32}/{slug}.{ext}` keys (svg, pdf) a build references. These are only checked:
-     * finalize writes them at upload, so a missing one is a content failure nothing here can fix,
-     * unless the bucket itself is missing, which is a store failure.
+     * `assets/{hash32}/{slug}.{ext}` keys (svg, pdf) a build references. These are never produced
+     * here (finalize writes them at upload), only checked, or copied under an `outputPrefix`, so a
+     * missing one is a content failure, unless the bucket itself is missing: a store failure.
      */
     statics?: readonly MaterializeTarget[];
+    /**
+     * Write every key `k` at `outputPrefix + k` instead, for a build whose writes must never land
+     * where production reads (a PR preview). A key production already stores is copied from there;
+     * the rest are transformed from the canonical originals. Production's own run, with no prefix,
+     * never reads beneath it. See `assertValidOutputPrefix` for what is accepted.
+     */
+    outputPrefix?: string;
     /** Store requests in flight at once. Default 8. */
     concurrency?: number;
     /**
@@ -106,6 +126,17 @@ export interface MaterializeOptions {
 export declare class SharpUnavailableError extends Error {
     constructor(cause: unknown);
 }
+/** `MaterializeOptions.outputPrefix` broke a rule of `assertValidOutputPrefix`; nothing was read or written. */
+export declare class InvalidOutputPrefixError extends Error {
+    constructor(prefix: string, reason: string);
+}
+/**
+ * Throws `InvalidOutputPrefixError` unless `prefix` is relative, ends in `/`, and is a run of
+ * `[A-Za-z0-9._-]` segments, none empty, `.` or `..`, whose first segments are not a canopy
+ * prefix. Production trusts whatever is under its own prefixes, so a write beneath one is a write
+ * production serves. Compared by segment: `assets-x/` is accepted, `assets/x/` is not.
+ */
+export declare function assertValidOutputPrefix(prefix: string): void;
 /**
  * @internal Exported for tests. Throttling, 5xx and dropped connections are transient. Any other
  * 4xx (AccessDenied, NoSuchBucket) is a configuration fault that a retry only delays.
@@ -115,8 +146,8 @@ export declare function isTransientStoreError(err: unknown): boolean;
  * Make every referenced transform key exist in `store`, and check every static key does. A key
  * already stored is left alone:
  * keys are content-addressed, so an existing object is the right one. sharp is loaded only when
- * something is missing, and a sharp that cannot load throws `SharpUnavailableError` rather than
- * failing each key.
+ * something must be transformed, and a sharp that cannot load throws `SharpUnavailableError` rather
+ * than failing each key. An invalid `outputPrefix` throws `InvalidOutputPrefixError` first.
  */
 export declare function materializeAssets(options: MaterializeOptions): Promise<MaterializeReport>;
 export {};

package/dist/assets/materialize.js

@@ -20,13 +20,14 @@ export const TRANSFORM_CACHE_CONTROL = 'public, max-age=31536000, immutable';
  */
 export const LAZY_TRANSFORM_TAG = { key: 'canopy-transform', value: 'lazy' };
 /**
- * Compute the transform `parsed` names from the asset's original and write it under
- * `canonicalKey`. `parsed` must come from `canonicalizeTransformPath`, so the stored pixels
- * always match their key. A rejection is a fact about the asset or the URL and is never worth
- * retrying; a thrown error belongs to the store or the environment. A 404's `error` names what
- * was missing, so a caller answering a browser replaces it.
+ * Compute the transform `parsed` names from the asset's original and write it under `key`: the
+ * canonical key, or that key beneath an output prefix. `parsed` must come from
+ * `canonicalizeTransformPath`, so the stored pixels always match their key. A rejection is a fact
+ * about the asset or the URL and is never worth retrying; a thrown error belongs to the store or
+ * the environment. A 404's `error` names what was missing, so a caller answering a browser
+ * replaces it.
  */
-export async function storeTransform(store, parsed, canonicalKey, options = {}) {
+export async function storeTransform(store, parsed, key, options = {}) {
     const meta = await store.getMeta(parsed.hash32);
     if (!meta) {
         return { ok: false, status: 404, error: `Asset ${parsed.hash32} has no meta in the store` };
@@ -58,15 +59,17 @@ export async function storeTransform(store, parsed, canonicalKey, options = {})
     if (!transformed.ok) {
         return { ok: false, status: transformed.status, error: transformed.error };
     }
-    await store.putPublicObject({
-        key: canonicalKey,
+    const stored = await store.putPublicObject({
+        key,
         data: transformed.data,
         contentType: transformed.contentType,
         cacheControl: TRANSFORM_CACHE_CONTROL,
         tags: options.tags,
     });
-    return { ok: true, data: transformed.data, contentType: transformed.contentType };
+    return { ok: true, data: transformed.data, contentType: transformed.contentType, stored };
 }
+/** The `schemaVersion` of every `MaterializeReport`; a consumer gating on the JSON checks it. */
+export const MATERIALIZE_REPORT_SCHEMA_VERSION = 1;
 /** sharp cannot load in this process, so nothing missing can be produced here. */
 export class SharpUnavailableError extends Error {
     constructor(cause) {
@@ -75,6 +78,43 @@ export class SharpUnavailableError extends Error {
         this.name = 'SharpUnavailableError';
     }
 }
+/** `MaterializeOptions.outputPrefix` broke a rule of `assertValidOutputPrefix`; nothing was read or written. */
+export class InvalidOutputPrefixError extends Error {
+    constructor(prefix, reason) {
+        super(`Invalid output prefix ${JSON.stringify(prefix)}: ${reason}`);
+        this.name = 'InvalidOutputPrefixError';
+    }
+}
+const OUTPUT_PREFIX_SEGMENT_RE = /^[A-Za-z0-9._-]+$/;
+const CANOPY_PREFIX_SEGMENTS = Object.values(ASSET_PREFIXES).map((prefix) => prefix.split('/'));
+/**
+ * Throws `InvalidOutputPrefixError` unless `prefix` is relative, ends in `/`, and is a run of
+ * `[A-Za-z0-9._-]` segments, none empty, `.` or `..`, whose first segments are not a canopy
+ * prefix. Production trusts whatever is under its own prefixes, so a write beneath one is a write
+ * production serves. Compared by segment: `assets-x/` is accepted, `assets/x/` is not.
+ */
+export function assertValidOutputPrefix(prefix) {
+    const refuse = (reason) => {
+        throw new InvalidOutputPrefixError(prefix, reason);
+    };
+    if (prefix.startsWith('/'))
+        refuse('it must be relative, with no leading /');
+    if (!prefix.endsWith('/'))
+        refuse('it must end in /');
+    const segments = prefix.slice(0, -1).split('/');
+    for (const segment of segments) {
+        if (segment === '')
+            refuse('it has an empty segment');
+        if (segment === '.' || segment === '..')
+            refuse(`it has a ${segment} segment`);
+        if (!OUTPUT_PREFIX_SEGMENT_RE.test(segment)) {
+            refuse(`segment ${JSON.stringify(segment)} has a character outside [A-Za-z0-9._-]`);
+        }
+    }
+    const canopy = CANOPY_PREFIX_SEGMENTS.find((prefixSegments) => prefixSegments.every((segment, i) => segments[i] === segment));
+    if (canopy)
+        refuse(`it begins with the canopy prefix ${canopy.join('/')}/`);
+}
 const DEFAULT_CONCURRENCY = 8;
 const DEFAULT_TRANSFORM_CONCURRENCY = 2;
 // eslint-disable-next-line security/detect-non-literal-regexp -- built from a constant
@@ -133,11 +173,14 @@ async function forEachBounded(items, limit, fn) {
  * Make every referenced transform key exist in `store`, and check every static key does. A key
  * already stored is left alone:
  * keys are content-addressed, so an existing object is the right one. sharp is loaded only when
- * something is missing, and a sharp that cannot load throws `SharpUnavailableError` rather than
- * failing each key.
+ * something must be transformed, and a sharp that cannot load throws `SharpUnavailableError` rather
+ * than failing each key. An invalid `outputPrefix` throws `InvalidOutputPrefixError` first.
  */
 export async function materializeAssets(options) {
-    const { store } = options;
+    const { store, outputPrefix } = options;
+    if (outputPrefix !== undefined)
+        assertValidOutputPrefix(outputPrefix);
+    const destOf = (key) => (outputPrefix ?? '') + key;
     const concurrency = Math.max(1, options.concurrency ?? DEFAULT_CONCURRENCY);
     const transformConcurrency = Math.max(1, options.transformConcurrency ?? DEFAULT_TRANSFORM_CONCURRENCY);
     const listThreshold = options.listThreshold ?? DEFAULT_LIST_THRESHOLD;
@@ -200,37 +243,51 @@ export async function materializeAssets(options) {
         group.push(target);
         byDirectives.set(target.directives, group);
     }
-    const toHead = [];
-    for (const [directives, group] of byDirectives) {
-        if (store.listPublicObjectKeys && group.length >= listThreshold) {
-            const listPrefix = `${transformPrefix}${directives}/`;
-            const listKeys = store.listPublicObjectKeys.bind(store);
-            try {
-                const found = await withRetry(async () => {
-                    const keys = [];
-                    for await (const key of listKeys(listPrefix))
-                        keys.push(key);
-                    return keys;
-                });
-                const listed = new Set(found);
-                for (const target of group) {
-                    if (listed.has(target.key))
-                        outcomes.set(target.key, { status: 'existed' });
-                }
+    const listOnce = async (prefix) => {
+        if (!store.listPublicObjectKeys)
+            return undefined;
+        const listKeys = store.listPublicObjectKeys.bind(store);
+        try {
+            return new Set(await withRetry(async () => {
+                const keys = [];
+                for await (const key of listKeys(prefix))
+                    keys.push(key);
+                return keys;
+            }));
+        }
+        catch {
+            // A listing that keeps failing costs only speed: its keys are HEADed instead, and each HEAD
+            // reports its own failure.
+            return undefined;
+        }
+    };
+    const listingsByDirectives = new Map();
+    if (store.listPublicObjectKeys) {
+        for (const [directives, group] of byDirectives) {
+            if (group.length < listThreshold)
                 continue;
-            }
-            catch {
-                // A listing that keeps failing costs only speed: HEAD the group instead, and let each
-                // HEAD report its own failure.
-            }
+            const listPrefix = `${transformPrefix}${directives}/`;
+            const dest = await listOnce(destOf(listPrefix));
+            const needsCanonical = outputPrefix !== undefined && group.some((target) => !dest?.has(destOf(target.key)));
+            const canonical = needsCanonical ? await listOnce(listPrefix) : undefined;
+            listingsByDirectives.set(directives, { dest, canonical });
         }
-        toHead.push(...group);
     }
-    await forEachBounded(toHead, concurrency, async (target) => {
+    // Every presence check goes through here. Without an output prefix a key's destination is the
+    // key itself, so this is one listing lookup or HEAD and never `canonical`.
+    const resolvePresence = async (key, listings = {}) => {
+        const isStored = async (storeKey, listing) => listing ? listing.has(storeKey) : withRetry(() => store.hasPublicObject(storeKey));
+        const dest = destOf(key);
+        if (await isStored(dest, listings.dest))
+            return 'dest';
+        if (dest === key)
+            return 'absent';
+        return (await isStored(key, listings.canonical)) ? 'canonical' : 'absent';
+    };
+    const presence = new Map();
+    await forEachBounded(valid, concurrency, async (target) => {
         try {
-            if (await withRetry(() => store.hasPublicObject(target.key))) {
-                outcomes.set(target.key, { status: 'existed' });
-            }
+            presence.set(target.key, await resolvePresence(target.key, listingsByDirectives.get(target.directives)));
         }
         catch (err) {
             fail(target.key, 'store', `Existence check failed: ${getErrorMessage(err)}`);
@@ -238,22 +295,51 @@ export async function materializeAssets(options) {
     });
     await forEachBounded(validStatics, concurrency, async (key) => {
         try {
+            let found = await resolvePresence(key);
             // A HEAD cannot tell a missing key from a missing bucket, and a static key has no
             // transform's meta read to tell them apart afterwards; a GET names which.
-            const exists = (await withRetry(() => store.hasPublicObject(key))) ||
-                (await withRetry(() => store.readPublicObject(key))) !== null;
-            if (exists) {
-                outcomes.set(key, { status: 'existed' });
+            if (found === 'absent' && (await withRetry(() => store.readPublicObject(key))) !== null) {
+                found = destOf(key) === key ? 'dest' : 'canonical';
+            }
+            presence.set(key, found);
+        }
+        catch (err) {
+            fail(key, 'store', `Existence check failed: ${getErrorMessage(err)}`);
+        }
+    });
+    const toCopy = [];
+    for (const [key, found] of presence) {
+        if (found === 'dest')
+            outcomes.set(key, { status: 'existed' });
+        else if (found === 'canonical')
+            toCopy.push(key);
+    }
+    await forEachBounded(toCopy, concurrency, async (key) => {
+        try {
+            let tries = 0;
+            const copied = await withRetry(() => {
+                tries++;
+                return store.copyPublicObject(key, destOf(key));
+            });
+            if (copied === 'source-missing') {
+                presence.set(key, 'absent');
             }
             else {
-                fail(key, 'content', 'No stored object; an svg or pdf is written at upload only');
+                // After a failed try, `already-exists` may be that try's own copy, as for a transform.
+                const copiedElsewhere = copied === 'already-exists' && tries === 1;
+                outcomes.set(key, { status: copiedElsewhere ? 'existed' : 'copied' });
             }
         }
         catch (err) {
-            fail(key, 'store', `Existence check failed: ${getErrorMessage(err)}`);
+            fail(key, 'store', `Copy failed: ${getErrorMessage(err)}`);
         }
     });
-    const missing = valid.filter((target) => !outcomes.has(target.key));
+    for (const key of validStatics) {
+        if (presence.get(key) === 'absent') {
+            fail(key, 'content', 'No stored object; an svg or pdf is written at upload only');
+        }
+    }
+    const missing = valid.filter((target) => presence.get(target.key) === 'absent');
     if (missing.length > 0) {
         try {
             await loadSharp();
@@ -264,9 +350,17 @@ export async function materializeAssets(options) {
     }
     await forEachBounded(missing, transformConcurrency, async (target) => {
         try {
-            const result = await withRetry(() => storeTransform(store, target.parsed, target.key));
+            let tries = 0;
+            const result = await withRetry(() => {
+                tries++;
+                return storeTransform(store, target.parsed, destOf(target.key));
+            });
             if (result.ok) {
-                outcomes.set(target.key, { status: 'created' });
+                // After a failed attempt, `already-exists` may be that attempt's own write, whose response
+                // was lost, so it counts as `created`: a release waiting on its `created` keys then waits
+                // on a key it may not have written, never skips one it did.
+                const createdElsewhere = result.stored === 'already-exists' && tries === 1;
+                outcomes.set(target.key, { status: createdElsewhere ? 'existed' : 'created' });
             }
             else {
                 fail(target.key, 'content', `${result.status}: ${result.error}`);
@@ -292,10 +386,13 @@ export async function materializeAssets(options) {
     });
     const count = (predicate) => results.filter(predicate).length;
     return {
+        schemaVersion: MATERIALIZE_REPORT_SCHEMA_VERSION,
+        ...(outputPrefix !== undefined ? { outputPrefix } : {}),
         summary: {
             total: results.length,
             existed: count((r) => r.status === 'existed'),
             created: count((r) => r.status === 'created'),
+            copied: count((r) => r.status === 'copied'),
             failed: count((r) => r.status === 'failed'),
             contentFailures: count((r) => r.status === 'failed' && r.failure === 'content'),
             storeFailures: count((r) => r.status === 'failed' && r.failure === 'store'),

package/dist/assets/store-local.d.ts

@@ -3,7 +3,7 @@
  * bucket-prefix layout as S3AssetStore (see keys.ts) so content behaves
  * identically across adapters.
  */
-import type { AssetMeta, AssetStore, BeginUploadInput, PublicObject, StagedUploadTarget } from './types.js';
+import type { AssetMeta, AssetStore, BeginUploadInput, CreateOnlyResult, PublicObject, StagedUploadTarget } from './types.js';
 export interface LocalAssetStoreOptions {
     /** Root directory. The five bucket prefixes are created as subdirectories under it. */
     root: string;
@@ -26,11 +26,20 @@ export declare class LocalAssetStore implements AssetStore {
      */
     private resolveKey;
     private headersSidecarPath;
-    private writeHeadersSidecar;
     private readHeadersSidecar;
     private readFileOrNull;
     private writeFile;
     private deleteFileIfPresent;
+    /** Link `tempPath` in at `filePath`; `false` when something is already there. */
+    private linkIfAbsent;
+    /**
+     * Create-only write of a blob and its headers sidecar. Each is written whole to a temp file, then
+     * `link()`ed into place, which fails with EEXIST rather than replacing (see docs/concurrency.md).
+     * The sidecar is linked first, so a reader never finds a blob without its headers. A sidecar
+     * already there was linked by an earlier writer of this key and is kept, as the blob is: the
+     * first writer's headers win, as on S3 (a static's Content-Disposition names its uploaded file).
+     */
+    private createExclusive;
     beginUpload(_input: BeginUploadInput): Promise<StagedUploadTarget>;
     /**
      * Staging methods accept caller-influenced keys (finalize receives the key
@@ -47,7 +56,7 @@ export declare class LocalAssetStore implements AssetStore {
         ext: string;
         data: Uint8Array;
         contentType: string;
-    }): Promise<void>;
+    }): Promise<CreateOnlyResult>;
     /** Ignores the `ext` hint: a directory read costs nothing here and needs no permission. */
     readOriginal(hash32: string): Promise<{
         data: Uint8Array;
@@ -62,7 +71,8 @@ export declare class LocalAssetStore implements AssetStore {
         cacheControl?: string;
         /** Ignored: tags exist for bucket lifecycle rules, and a local store has none. */
         tags?: Readonly<Record<string, string>>;
-    }): Promise<void>;
+    }): Promise<CreateOnlyResult>;
+    copyPublicObject(sourceKey: string, destKey: string): Promise<CreateOnlyResult | 'source-missing'>;
     readPublicObject(key: string): Promise<PublicObject | null>;
     hasPublicObject(key: string): Promise<boolean>;
     /**
@@ -73,7 +83,7 @@ export declare class LocalAssetStore implements AssetStore {
      * always clobbers the destination, which would let the second writer
      * silently overwrite the first instead of losing cleanly.
      */
-    putMetaIfAbsent(hash32: string, meta: AssetMeta): Promise<'created' | 'already-exists'>;
+    putMetaIfAbsent(hash32: string, meta: AssetMeta): Promise<CreateOnlyResult>;
     getMeta(hash32: string): Promise<AssetMeta | null>;
     listMeta(input?: {
         cursor?: string;