canopycms 0.11.0 → 0.12.0

package/dist/api/branch-entry-changes.js

@@ -2,19 +2,22 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { z } from 'zod';
 import { entryRefFromRepoPath, entryRefFromRepoPathShape, parseEntryParts, } from '../content-listing.js';
-import { ContentStore, ContentStoreError } from '../content-store.js';
+import { BranchSyncingError, ContentConflictError, ContentStore, ContentStoreError, } from '../content-store.js';
 import { resolveCollectionPath } from '../content-id-index.js';
 import { BaseBranchMissingError } from '../git-manager.js';
 import { getBranchProtection } from '../authorization/protected-branch.js';
+import { SchemaOps, SchemaStoreBusyError } from '../schema/schema-store.js';
+import { canopyLogWarn } from '../utils/logger.js';
+import { isRebaseInProgress } from '../utils/git.js';
 import { baseBranchOf } from '../utils/base-branch.js';
 import { findBodyFieldName } from '../utils/body-field.js';
 import { entryAsRead } from '../utils/calendar-day.js';
-import { isNodeError, isNotFoundError } from '../utils/error.js';
+import { isNodeError, isNotFoundError, sanitizeErrorMessage } from '../utils/error.js';
 import { getFormatExtension } from '../utils/format.js';
 import { entryLogicalPath } from '../paths/index.js';
 import { defineEndpoint } from './route-builder.js';
 import { branchNameSchema, contentIdSchema, logicalPathSchema } from './validators.js';
-import { branchReadFailedResponse, readWhileSteady, unsteadyReadResponse, } from './branch-changes.js';
+import { branchReadFailedResponse, readWhileSteady, SYNCING_ERROR, unsteadyReadResponse, } from './branch-changes.js';
 /** The most of a side's file read, so one huge file can't hold the API or the browser. */
 const MAX_SIDE_BYTES = 1024 * 1024;
 const NOT_COMPARABLE_ERROR = "This entry can't be compared.";
@@ -110,14 +113,13 @@ const readAfter = async (store, flatSchema, target, id) => {
     }
 };
 /**
- * The entry at `logicalPath` in `mergeBase`'s tree, matched by `contentId` when there is one.
- * Looked for under the collection's directory first, then the whole content root when that
- * directory isn't in the base tree (a collection renamed or deleted on the branch). Files map
- * to entries as GET /:branch/changes maps them, so the entry it lists resolves to the same
- * file here. A base file whose collection or entry type the schema no longer has is keyed with
- * `afterFields`, the saved side's, so its unchanged items carry the keys the saved side's do.
+ * The file of the entry at `logicalPath` in `mergeBase`'s tree, matched by `contentId` when
+ * there is one. Looked for under the collection's directory first, then the whole content root
+ * when that directory isn't in the base tree (a collection renamed or deleted on the branch).
+ * Files map to entries as GET /:branch/changes maps them, so the entry it lists resolves to the
+ * same file here.
  */
-const readBefore = async (git, mergeBase, logicalPath, match, branchContext, contentRoot) => {
+const findBaseFile = async (git, mergeBase, logicalPath, contentId, branchContext, contentRoot) => {
     const { flatSchema, branchRoot } = branchContext;
     const collectionPath = logicalPath.slice(0, logicalPath.lastIndexOf('/'));
     const collectionDir = await resolveCollectionPath(branchRoot, collectionPath);
@@ -132,35 +134,9 @@ const readBefore = async (git, mergeBase, logicalPath, match, branchContext, con
             const ref = placed.kind === 'other' ? entryRefFromRepoPathShape(file.path, contentRoot) : placed;
             if (ref?.kind !== 'entry' || ref.logicalPath !== logicalPath)
                 continue;
-            if (match.contentId !== undefined && ref.contentId !== match.contentId)
+            if (contentId !== undefined && ref.contentId !== contentId)
                 continue;
-            if (file.size > MAX_SIDE_BYTES)
-                return 'too-large';
-            const entryType = entryTypeIn(flatSchema, ref.collectionPath, ref.entryType);
-            const fields = entryType?.schema ?? match.afterFields ?? [];
-            // An entry type the schema no longer has is parsed by its extension.
-            const format = entryType?.format ?? FORMATS.find((f) => file.path.endsWith(getFormatExtension(f)));
-            if (!format)
-                return 'unreadable';
-            const raw = await git.showFile(mergeBase, file.path);
-            if (raw === undefined)
-                return undefined;
-            let parsed;
-            try {
-                parsed = parseEntryParts(raw, format);
-            }
-            catch {
-                return 'unreadable';
-            }
-            return {
-                format,
-                entryType: ref.entryType,
-                data: entryAsRead(fields, parsed.data),
-                ...(parsed.body !== undefined && {
-                    body: parsed.body,
-                    bodyFieldName: findBodyFieldName(fields),
-                }),
-            };
+            return { path: file.path, size: file.size, ref, placed: placed.kind === 'entry' };
         }
         // The collection's directory is in the base tree, so an entry not in it is new.
         if (files.length > 0)
@@ -168,6 +144,44 @@ const readBefore = async (git, mergeBase, logicalPath, match, branchContext, con
     }
     return undefined;
 };
+/**
+ * The entry at `logicalPath` in `mergeBase`'s tree (`findBaseFile`), read as the editor reads
+ * one. A base file whose collection or entry type the schema no longer has is keyed with
+ * `afterFields`, the saved side's, so its unchanged items carry the keys the saved side's do.
+ */
+const readBefore = async (git, mergeBase, logicalPath, match, branchContext, contentRoot) => {
+    const file = await findBaseFile(git, mergeBase, logicalPath, match.contentId, branchContext, contentRoot);
+    if (!file)
+        return undefined;
+    const { ref } = file;
+    if (file.size > MAX_SIDE_BYTES)
+        return 'too-large';
+    const entryType = entryTypeIn(branchContext.flatSchema, ref.collectionPath, ref.entryType);
+    const fields = entryType?.schema ?? match.afterFields ?? [];
+    // An entry type the schema no longer has is parsed by its extension.
+    const format = entryType?.format ?? FORMATS.find((f) => file.path.endsWith(getFormatExtension(f)));
+    if (!format)
+        return 'unreadable';
+    const raw = await git.showFile(mergeBase, file.path);
+    if (raw === undefined)
+        return undefined;
+    let parsed;
+    try {
+        parsed = parseEntryParts(raw, format);
+    }
+    catch {
+        return 'unreadable';
+    }
+    return {
+        format,
+        entryType: ref.entryType,
+        data: entryAsRead(fields, parsed.data),
+        ...(parsed.body !== undefined && {
+            body: parsed.body,
+            bodyFieldName: findBodyFieldName(fields),
+        }),
+    };
+};
 const entryChangeHandler = async (gc, ctx, req, params) => {
     const { branchContext } = gc;
     const { config } = ctx.services;
@@ -255,6 +269,226 @@ export const readBranchEntryChange = defineEndpoint({
     guards: ['branchAccessWithSchema'],
     handler: entryChangeHandler,
 });
+const restoreParamsSchema = z.object({
+    branch: branchNameSchema,
+    entryPath: logicalPathSchema,
+});
+const restoreBodySchema = z.object({
+    /** The deleted entry's content id, which the base file must carry and the restore keeps. */
+    id: contentIdSchema,
+});
+const NOT_RESTORABLE_ERROR = "This entry isn't on the base branch, so it can't be restored.";
+const TYPE_CHANGED_ERROR = "This entry's type or format has changed since it was deleted, so it can't be restored.";
+const TOO_LARGE_TO_RESTORE_ERROR = 'This entry is too large to restore here.';
+const UNREADABLE_TO_RESTORE_ERROR = "This entry's saved file doesn't read, so it can't be restored.";
+/** `order` with `id` put back after its nearest predecessor in `baseOrder` that `order` holds. */
+const orderWith = (order, id, baseOrder) => {
+    const at = baseOrder.indexOf(id);
+    for (let i = at - 1; i >= 0; i--) {
+        const index = order.indexOf(baseOrder[i]);
+        if (index >= 0)
+            return [...order.slice(0, index + 1), id, ...order.slice(index + 1)];
+    }
+    return [id, ...order];
+};
+/** A collection's `order` in its `.collection.json` at `rev`, or undefined when it has none. */
+const orderAt = async (git, rev, collectionRepoDir) => {
+    const raw = await git.showFile(rev, `${collectionRepoDir}/.collection.json`);
+    if (raw === undefined)
+        return undefined;
+    try {
+        const order = JSON.parse(raw)?.order;
+        return Array.isArray(order) && order.every((id) => typeof id === 'string') ? order : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/** Git failing in a restore's pre-write HEAD check, answered as a failed read is. */
+class HeadReadError extends Error {
+    constructor(failure) {
+        super("Couldn't read the branch's HEAD");
+        this.failure = failure;
+    }
+}
+const restoreEntryHandler = async (gc, ctx, req, params, body) => {
+    const { branchContext } = gc;
+    const { branchRoot } = branchContext;
+    const { config } = ctx.services;
+    const base = branchContext.branch.baseBranch ?? baseBranchOf(config);
+    const contentRoot = config.contentRoot || 'content';
+    const store = new ContentStore(branchRoot, branchContext.flatSchema, {
+        contentRootName: contentRoot,
+    });
+    const target = canonicalPath(store, underContentRoot(params.entryPath, contentRoot));
+    const notRestorable = {
+        ok: false,
+        status: 404,
+        error: NOT_RESTORABLE_ERROR,
+    };
+    if (!target.stored)
+        return notRestorable;
+    const checkAccess = await ctx.services.createContentAccessChecker(branchContext, branchRoot, req.user);
+    if (!checkAccess(target.logicalPath, 'edit').allowed) {
+        return { ok: false, status: 403, error: 'Forbidden' };
+    }
+    const { collectionPath, slug } = target.stored;
+    const collectionDir = await resolveCollectionPath(branchRoot, collectionPath);
+    const collectionRepoDir = collectionDir && path.relative(branchRoot, collectionDir).split(path.sep).join('/');
+    const git = ctx.services.createGitManagerFor(branchRoot, {
+        baseBranch: branchContext.branch.baseBranch,
+    });
+    let read;
+    try {
+        read = await readWhileSteady(branchRoot, git, async () => {
+            const mergeBase = await git.mergeBaseWithBase();
+            if (!mergeBase)
+                return undefined;
+            const file = await findBaseFile(git, mergeBase, target.logicalPath, body.id, branchContext, contentRoot);
+            if (!file)
+                return undefined;
+            // Only a file the current schema places as this entry type, by name and extension, goes
+            // back: another format's bytes under this type's extension would not read.
+            if (!file.placed)
+                return 'type-changed';
+            if (file.size > MAX_SIDE_BYTES)
+                return 'too-large';
+            const raw = await git.showFile(mergeBase, file.path);
+            if (raw === undefined)
+                return undefined;
+            const baseOrder = collectionRepoDir
+                ? await orderAt(git, mergeBase, collectionRepoDir)
+                : undefined;
+            return {
+                raw,
+                entryType: file.ref.entryType,
+                head: await git.headSha(),
+                ...(baseOrder && { baseOrder }),
+            };
+        });
+    }
+    catch (err) {
+        if (err instanceof BaseBranchMissingError)
+            return notRestorable;
+        return branchReadFailedResponse(branchContext.branch.name, base, err);
+    }
+    if (!read.steady)
+        return unsteadyReadResponse(read.reason, base);
+    const entry = read.value;
+    if (entry === 'too-large')
+        return { ok: false, status: 413, error: TOO_LARGE_TO_RESTORE_ERROR };
+    if (entry === 'type-changed')
+        return { ok: false, status: 409, error: TYPE_CHANGED_ERROR };
+    if (!entry)
+        return notRestorable;
+    const entryType = entryTypeIn(branchContext.flatSchema, collectionPath, entry.entryType);
+    if (!entryType)
+        return { ok: false, status: 409, error: TYPE_CHANGED_ERROR };
+    try {
+        parseEntryParts(entry.raw, entryType.format);
+    }
+    catch {
+        return { ok: false, status: 422, error: UNREADABLE_TO_RESTORE_ERROR };
+    }
+    // As a create checks it (SCH-H3, api/content.ts), best-effort: count-then-write isn't atomic.
+    const { maxItems } = entryType;
+    if (maxItems !== undefined &&
+        (await store.countEntriesOfType(collectionPath, entry.entryType)) >= maxItems) {
+        return {
+            ok: false,
+            status: 422,
+            error: `Cannot restore entry: type "${entry.entryType}" allows at most ${maxItems} ${maxItems === 1 ? 'entry' : 'entries'}`,
+        };
+    }
+    try {
+        await store.restore(collectionPath, slug, { id: body.id, entryTypeName: entry.entryType, raw: entry.raw }, {
+            // The bytes are the merge base's as HEAD stood at the read; a sync since may have
+            // updated the entry upstream, so a moved HEAD refuses rather than reverting that.
+            beforeWrite: async () => {
+                let moved;
+                try {
+                    moved = (await isRebaseInProgress(branchRoot)) || (await git.headSha()) !== entry.head;
+                }
+                catch (err) {
+                    throw new HeadReadError(err);
+                }
+                if (moved)
+                    throw new BranchSyncingError(SYNCING_ERROR(base));
+            },
+        });
+    }
+    catch (err) {
+        if (err instanceof HeadReadError) {
+            return branchReadFailedResponse(branchContext.branch.name, base, err.failure);
+        }
+        if (err instanceof BranchSyncingError) {
+            return {
+                ok: false,
+                status: 409,
+                error: err.message,
+                code: err.outcome === 'unknown' ? 'WRITE_OUTCOME_UNKNOWN' : 'BRANCH_SYNCING',
+            };
+        }
+        // A refusal the editor can act on: the slug or the id is taken, or a URL is contested.
+        if (err instanceof ContentConflictError)
+            return { ok: false, status: 409, error: err.message };
+        if (err instanceof ContentStoreError) {
+            return { ok: false, status: 400, error: sanitizeErrorMessage(err.message) };
+        }
+        throw err;
+    }
+    const warning = await restoreOrder(ctx, branchContext, collectionPath, body.id, entry.baseOrder);
+    return {
+        ok: true,
+        status: 200,
+        data: { logicalPath: target.logicalPath, contentId: body.id, ...(warning && { warning }) },
+    };
+};
+/**
+ * Puts a restored entry's id back in its collection's manual order, after its nearest neighbour
+ * at the base, undoing what a delete took out (api/entries.ts). Best-effort: the entry is back
+ * either way, so a failure is a warning. Runs after the restore, whose content-write lock a
+ * schema write also takes.
+ */
+const restoreOrder = async (ctx, branchContext, collectionPath, id, baseOrder) => {
+    const collection = branchContext.flatSchema.find((item) => item.type === 'collection' && item.logicalPath === collectionPath);
+    const order = collection?.order;
+    if (!order || !baseOrder?.includes(id) || order.includes(id))
+        return undefined;
+    const schemaStore = new SchemaOps(path.join(branchContext.branchRoot, ctx.services.config.contentRoot || 'content'), ctx.services.entrySchemaRegistry, ctx.services, branchContext.branchRoot);
+    try {
+        await schemaStore.updateOrder(collectionPath, orderWith(order, id, baseOrder));
+        return undefined;
+    }
+    catch (err) {
+        // An `'unknown'` outcome means the update ran to completion.
+        if (err instanceof SchemaStoreBusyError && err.outcome === 'unknown')
+            return undefined;
+        canopyLogWarn(`CanopyCMS: restored ${collectionPath}/${id} but not its place in the order:`, err);
+        return 'Entry restored, but its place in the collection order couldn’t be put back, so it is listed last.';
+    }
+};
+/**
+ * Puts back an entry deleted on the branch, as the commit the branch forked from holds it, with
+ * its content id (`ContentStore.restore`).
+ * POST /:branch/restore-entry/...entryPath
+ * @internal Exported for tests.
+ */
+export const restoreBranchEntry = defineEndpoint({
+    namespace: 'changes',
+    name: 'restore',
+    method: 'POST',
+    path: '/:branch/restore-entry/...entryPath',
+    params: restoreParamsSchema,
+    body: restoreBodySchema,
+    bodyType: 'RestoreEntryBody',
+    responseType: 'RestoreEntryResponse',
+    response: {},
+    defaultMockData: { logicalPath: '', contentId: '' },
+    guards: ['schema', 'writableBranch'],
+    handler: restoreEntryHandler,
+});
 export const BRANCH_ENTRY_CHANGE_ROUTES = {
     entry: readBranchEntryChange,
+    restore: restoreBranchEntry,
 };

package/dist/api/client.d.ts

@@ -10,7 +10,7 @@ export { isApiTimeoutError, WRITE_TIMED_OUT_MESSAGE, type RequestOptions } from
 import type { OperatingMode } from '../operating-mode/types.js';
 import type { BranchDeleteResponse, BranchListItemResponse, BranchListResponse, CreateBranchBody, UpdateBranchAccessBody } from './branch.js';
 import type { BranchChangesResponse } from './branch-changes.js';
-import type { BranchEntryChangeResponse } from './branch-entry-changes.js';
+import type { BranchEntryChangeResponse, RestoreEntryBody, RestoreEntryResponse } from './branch-entry-changes.js';
 import type { BranchMergeResponse, RequestChangesBody, SubmitBranchBody, SubmitBranchResponse } from './branch-status.js';
 import type { AdminDeleteTaskResponse, AdminRetryTaskResponse, AdminStatusResponse, AdminTasksResponse, BranchHealthResponse, DeleteArchivedBranchesBody, DeleteArchivedBranchesResponse, DismissUnpublishedResponse, PurgeBranchDirResponse, RepairBranchDirResponse, RepairContentDuplicatesResponse } from './admin.js';
 import type { AddCommentBody, AddCommentResponse, CommentsResponse, ResolveCommentResponse } from './comments.js';
@@ -92,6 +92,8 @@ export declare class CanopyApiClient {
         list: (params: Record<string, string>, options?: RequestOptions) => Promise<BranchChangesResponse>;
         /** GET /:branch/changes/...entryPath */
         entry: (params: Record<string, string>, options?: RequestOptions) => Promise<BranchEntryChangeResponse>;
+        /** POST /:branch/restore-entry/...entryPath */
+        restore: (params: Record<string, string>, body: RestoreEntryBody, options?: RequestOptions) => Promise<RestoreEntryResponse>;
     };
     readonly workflow: {
         /** POST /:branch/withdraw */

package/dist/api/client.js

@@ -50,6 +50,10 @@ export class CanopyApiClient {
             entry: (params, options) => {
                 return this.request('GET', this.buildPath('/:branch/changes/...entryPath', params), undefined, 'standard', options);
             },
+            /** POST /:branch/restore-entry/...entryPath */
+            restore: (params, body, options) => {
+                return this.request('POST', this.buildPath('/:branch/restore-entry/...entryPath', params), body, 'standard', options);
+            },
         };
         this.workflow = {
             /** POST /:branch/withdraw */

package/dist/cli/cli.js

@@ -8454,7 +8454,7 @@ async function generateAIContentCLI(options) {
   console.log(`  Output: ${result.outputDir}
 `);
 }
-var __defProp3, __getOwnPropNames3, __esm3, __export3, init_error3, init_atomic_write2, init_field_traversal, ITEM_KEY, ITEM_KEY_PATTERN, isItemKey, BASE58, isListField, init_item_keys, active2, init_logger2, SENTINEL_BASE2, DOT_SEGMENT2, init_sanitize_href2, init_normalize, RESERVED_SETTINGS_BRANCH_PREFIX2, init_branch_name, BASE58_PATTERN2, CONTENT_ID_PATTERN2, PHYSICAL_SEGMENT_PATTERN2, MAX_BRANCH_NAME_LENGTH2, init_validation, ROOT_COLLECTION_ID, init_types2, normalizePathValue, flattenSchema, init_flatten, scalarFieldTypes2, markdownFieldTypes2, primitiveFieldTypes2, fieldTypes2, init_types22, SAFE_HTML_TAGS2, COMPONENT_NAME2, MDX_BINDINGS2, FORBIDDEN_ATTRIBUTES2, init_mdx_allowlist2, fieldBaseSchema2, selectOptionSchema2, referenceOptionSchema2, primitiveFieldSchema2, mdxPropAllowSchema2, mdxAllowlistSchema2, markdownFieldSchema2, ASPECT_RATIO_RE2, imageFieldSchema2, selectFieldSchema2, referenceSortFieldSchema2, referenceFieldSchema2, fieldHolder2, blockSchema2, blockFieldSchema2, objectFieldSchema2, inlineGroupFieldSchema2, customFieldSchema2, knownFieldSchema2, fieldSchema2, init_field2, relativePathSchema2, entryTypeSchema2, collectionSchema2, init_collection2, uploadTargetUrlSchema2, previewPrefixSchema2, editorUrlSchema2, init_url2, mediaSchema2, init_media2, defaultBranchAccessSchema2, defaultPathAccessLevelSchema2, defaultPathAccessLevelsSchema2, defaultPathAccessSchema2, defaultBaseBranchSchema2, defaultRemoteNameSchema2, defaultRemoteUrlSchema2, gitBotAuthorNameSchema2, gitBotAuthorEmailSchema2, githubTokenEnvVarSchema2, operatingModeSchema2, deployedAsSchema2, contentRootSchema2, sourceRootSchema2, basePathSchema2, deploymentNameSchema2, devContentSyncSchema2, devConfigSchema2, editorConfigSchema2, seoFieldNameSchema2, seoSchema2, CanopyConfigSchema2, DEFAULT_PROD_WORKSPACE2, init_config3, SERVER_MODE_ENV_VAR, BROWSER_MODE_ENV_VAR, warned22, init_mode_env, forEachReferenceField, init_validation2, ProdClientSafeStrategy2, DevClientSafeStrategy2, clientStrategyCache, init_client_safe_strategy, warned3, VALID_DEPLOYMENT_NAME2, isValidDeploymentName2, init_deployment_name, warned4, DEPLOYMENT_PLACEHOLDER2, DEFAULT_BRANCH_NAMESPACE_TEMPLATE2, BRANCH_NAMESPACE_ENV2, init_branch_namespace, init_config22, ProdStrategy2, DevStrategy2, strategyCache2, init_client_unsafe_strategy, operating_mode_exports, init_operating_mode, task_queue_config_exports2, init_task_queue_config2, worker_status_exports, WORKER_STATUS_FILE, init_worker_status, BLOCK_DISCRIMINATOR_KEYS, BLOCK_STRUCTURAL_KEYS, DAY, MS_PER_DAY, isRealDay, dayParts, isCalendarDay, dayOfBareDate, mapItems, blockItemWithDays, valueWithDays, entryAsRead, envFlag2, LOG_LEVELS2, DebugLogger2, testLogger2, MARKDOWN_EXPORT_OPTIONS, BULLETS, DELIMITERS, EMPHASIS, STRONG, RULE, WORD_CHAR, GAP, Restyler, END, FRESH, LINE_WIDTH, MIN_LINE_WIDTH, SourceSplicer, log2, MAX_LCS_CELLS, Splicer, log22, EVIDENCE_MAX_DEPTH, log3, locks, PROVISIONING_LOCK_STALE_MS, sleep, META_DIR, CONTENT_WRITE_LOCK_NAME, DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS, ContentWriteLockBusyError, sleep2, CONTENT_WRITE_LOCK_STALE_MS, heldRoots, getFormatExtension, isDataOnlyFormat, asRecord, DEFAULT_SEO_FIELD_NAMES, asRecord2, asText, asFlag, asImageUrl, asOgType, asTwitterCard, RESTRICTED_REFERENCE_MARKER, SEO_GROUP_FIELDS, MAX_WARNED, warned5, SchemaUnavailableError, isValidId, parseTypedFilename, EMPTY_LOGICAL_PATH, ENTRY_EXTENSIONS, ContentIdIndex, CONTENT_EXTENSIONS, registry, finalization, log4, META_DIR2, entryTypeMetaSchema, collectionMetaSchema, rootCollectionMetaSchema, fingerprints, editDistance, closestName, forEachEntryType, collectEntryTypeNames, validateReferenceEntryTypes, isDeployedStatic, isBuildMode, readsFromCheckout, STATIC_DEPLOY_USER, storage, log5, BaseBranchUnresolvedError, NETWORK_SCHEME_PATTERN, TRANSPORT_HELPER_PATTERN, LEADING_OPTION_PATTERN, WINDOWS_DRIVE_PATTERN, COLON_BEFORE_SLASH_PATTERN, MISSING_REMOTE_REF_REASONS, CANOPY_META_DIR, SCHEMA_CACHE_VERSION, MTIME_CHECK_DEBOUNCE_MS, SNAPSHOT_MEMO_MAX_BYTES, SCHEMA_CACHE_FILE, SCHEMA_GENERATION_RESOURCE, reportedIssues, BranchSchemaCache, RESOURCE, BranchPathError, resolveContentBranchesRoot, ContentStoreError, ContentConflictError, EntryGoneError, BranchSyncingError, DuplicateContentIdError, UrlPathConflictError, isEmptyFieldValue, DEFAULT_INDEX_FRESHNESS_INTERVAL_MS, FORCED_REFRESH_MIN_INTERVAL_MS, STALE_LOOKUP, isMissingReference, createReferenceResolveCache, ContentStore, ATTR_CONTENT, BLOCK_PREFIX, BLOCK_SUFFIX, BLOCK_RESTORE_RE, INLINE_PREFIX, INLINE_SUFFIX, INLINE_RESTORE_RE, DEFAULT_REFERENCE_RENDERING, FLAT_CELL_TYPES, log6, BASE58_CHAR, ENTRY_LINK_PATTERN, INLINE_LINK_TARGET, BranchMetadataCorruptError, BRANCH_META_DIR, BRANCH_META_FILE, branchMetadataFilePath, UNKNOWN_TIME, enumOf, branchMetadataShape, branchMetadataSchema, branchMetadataFileSchema, log7, REGISTRY_FILE, REGISTRY_STALE_FILE, REGISTRY_TEMP_FILE, REGISTRY_VERSION, RESOURCE2, GET_MISS_REFRESH_MIN_INTERVAL_MS, snapshotSchema, reportedUnreadable, BranchRegistry, log8, OccWriteConflictError, CURRENT_SCHEMA_VERSION, BranchMetadataConflictError, BranchMetadataFileManager, loadBranchContext, GitProcessError, STDERR_CAP_BYTES, KILL_GRACE_MS, log9, GIT_ENV_PASSTHROUGH, FORCE_C_LOCALE, GIT_NETWORK_ENV_PASSTHROUGH, NO_AUTO_GC_CONFIG, HASH_INACTIVITY_TIMEOUT_MS, MAX_HASH_RUNS, LS_REMOTE_INACTIVITY_TIMEOUT_MS, symlinkBlobSha, REMOTE_GIT_CONFIG, REMOTE_GIT_MAX_LOOSE_OBJECTS, REMOTE_GIT_MAX_PACKS, PARALLEL_CHECKOUT_ARGS, remoteInitLocks, GITHUB_TRACKING_REF_PREFIX, BaseBranchMissingError, GitConflictError, GitRemoteRefMissingError, RemoteNotReadyError, SettingsRemoteUnreadableError, SettingsBranchDivergedError, SETTINGS_BRANCH_FILES, SettingsBranchHasContentHistoryError, GitManager, PUBLISH_LOCK_WAIT_MS, CREATE_RESIDUE_MIN_QUIET_MS, STAGING_MAX_AGE_MS, REPAIR_MAX_AGE_MS, DELETING_MAX_AGE_MS, SETTINGS_TRASH_MAX_AGE_MS, BranchProvisioningBusyError, BranchDirOccupiedError, STAGING_PREFIX, REPAIR_PREFIX, TRASH_PREFIX, stagingDirName, NO_GIT, RENAME_BLOCKED, SPARSE_CONE_RECORD, defaultSink, sink, ProvisionLog, testHooks, provisionsInFlight, BranchWorkspaceManager, AI_USER_ID, log10, normalizePath, parseEntryParts, parseEntryData, readEntryData, createReferenceResolver, withoutUnavailableEntries, resolveCollectionItemReferences, looksLikeMalformedEntry, listCollectionEntries, MAX_INPUT_PIXELS, CROP_PRECISION, KNOWN_FIELD_TYPES, STRING_FIELD_TYPES, selectOptionValues, GENERATED_RECORD_FILENAME, SAFE_BUILD_ID, BUILD_ID_RULE, jiti;
+var __defProp3, __getOwnPropNames3, __esm3, __export3, init_error3, init_atomic_write2, init_field_traversal, ITEM_KEY, ITEM_KEY_PATTERN, isItemKey, BASE58, isListField, init_item_keys, active2, init_logger2, SENTINEL_BASE2, DOT_SEGMENT2, init_sanitize_href2, init_normalize, RESERVED_SETTINGS_BRANCH_PREFIX2, init_branch_name, BASE58_PATTERN2, CONTENT_ID_PATTERN2, PHYSICAL_SEGMENT_PATTERN2, MAX_BRANCH_NAME_LENGTH2, init_validation, ROOT_COLLECTION_ID, init_types2, normalizePathValue, flattenSchema, init_flatten, scalarFieldTypes2, markdownFieldTypes2, primitiveFieldTypes2, fieldTypes2, init_types22, SAFE_HTML_TAGS2, COMPONENT_NAME2, MDX_BINDINGS2, FORBIDDEN_ATTRIBUTES2, init_mdx_allowlist2, fieldBaseSchema2, selectOptionSchema2, referenceOptionSchema2, primitiveFieldSchema2, mdxPropAllowSchema2, mdxAllowlistSchema2, markdownFieldSchema2, ASPECT_RATIO_RE2, imageFieldSchema2, selectFieldSchema2, referenceSortFieldSchema2, referenceFieldSchema2, fieldHolder2, blockSchema2, blockFieldSchema2, objectFieldSchema2, inlineGroupFieldSchema2, customFieldSchema2, knownFieldSchema2, fieldSchema2, init_field2, relativePathSchema2, entryTypeSchema2, collectionSchema2, init_collection2, uploadTargetUrlSchema2, previewPrefixSchema2, editorUrlSchema2, init_url2, mediaSchema2, init_media2, defaultBranchAccessSchema2, defaultPathAccessLevelSchema2, defaultPathAccessLevelsSchema2, defaultPathAccessSchema2, defaultBaseBranchSchema2, defaultRemoteNameSchema2, defaultRemoteUrlSchema2, gitBotAuthorNameSchema2, gitBotAuthorEmailSchema2, githubTokenEnvVarSchema2, operatingModeSchema2, deployedAsSchema2, contentRootSchema2, sourceRootSchema2, basePathSchema2, deploymentNameSchema2, devContentSyncSchema2, devConfigSchema2, editorConfigSchema2, seoFieldNameSchema2, seoSchema2, CanopyConfigSchema2, DEFAULT_PROD_WORKSPACE2, init_config3, SERVER_MODE_ENV_VAR, BROWSER_MODE_ENV_VAR, warned22, init_mode_env, forEachReferenceField, init_validation2, ProdClientSafeStrategy2, DevClientSafeStrategy2, clientStrategyCache, init_client_safe_strategy, warned3, VALID_DEPLOYMENT_NAME2, isValidDeploymentName2, init_deployment_name, warned4, DEPLOYMENT_PLACEHOLDER2, DEFAULT_BRANCH_NAMESPACE_TEMPLATE2, BRANCH_NAMESPACE_ENV2, init_branch_namespace, init_config22, ProdStrategy2, DevStrategy2, strategyCache2, init_client_unsafe_strategy, operating_mode_exports, init_operating_mode, task_queue_config_exports2, init_task_queue_config2, worker_status_exports, WORKER_STATUS_FILE, init_worker_status, BLOCK_DISCRIMINATOR_KEYS, BLOCK_STRUCTURAL_KEYS, DAY, MS_PER_DAY, isRealDay, dayParts, isCalendarDay, dayOfBareDate, mapItems, blockItemWithDays, valueWithDays, entryAsRead, envFlag2, LOG_LEVELS2, DebugLogger2, testLogger2, MARKDOWN_EXPORT_OPTIONS, BULLETS, DELIMITERS, EMPHASIS, STRONG, RULE, WORD_CHAR, GAP, Restyler, END, FRESH, LINE_WIDTH, MIN_LINE_WIDTH, SourceSplicer, log2, MAX_LCS_CELLS, Splicer, log22, EVIDENCE_MAX_DEPTH, log3, locks, PROVISIONING_LOCK_STALE_MS, sleep, META_DIR, CONTENT_WRITE_LOCK_NAME, DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS, ContentWriteLockBusyError, sleep2, CONTENT_WRITE_LOCK_STALE_MS, heldRoots, getFormatExtension, isDataOnlyFormat, asRecord, DEFAULT_SEO_FIELD_NAMES, asRecord2, asText, asFlag, asImageUrl, asOgType, asTwitterCard, RESTRICTED_REFERENCE_MARKER, SEO_GROUP_FIELDS, MAX_WARNED, warned5, SchemaUnavailableError, isValidId, parseTypedFilename, EMPTY_LOGICAL_PATH, ENTRY_EXTENSIONS, ContentIdIndex, CONTENT_EXTENSIONS, registry, finalization, log4, META_DIR2, entryTypeMetaSchema, collectionMetaSchema, rootCollectionMetaSchema, fingerprints, editDistance, closestName, forEachEntryType, collectEntryTypeNames, validateReferenceEntryTypes, isDeployedStatic, isBuildMode, readsFromCheckout, STATIC_DEPLOY_USER, storage, log5, BaseBranchUnresolvedError, NETWORK_SCHEME_PATTERN, TRANSPORT_HELPER_PATTERN, LEADING_OPTION_PATTERN, WINDOWS_DRIVE_PATTERN, COLON_BEFORE_SLASH_PATTERN, MISSING_REMOTE_REF_REASONS, CANOPY_META_DIR, SCHEMA_CACHE_VERSION, MTIME_CHECK_DEBOUNCE_MS, SNAPSHOT_MEMO_MAX_BYTES, SCHEMA_CACHE_FILE, SCHEMA_GENERATION_RESOURCE, reportedIssues, BranchSchemaCache, RESOURCE, BranchPathError, resolveContentBranchesRoot, ContentStoreError, RESTORE_SLUG_TAKEN_MESSAGE, RESTORE_ID_TAKEN_MESSAGE, ContentConflictError, EntryGoneError, BranchSyncingError, DuplicateContentIdError, UrlPathConflictError, isEmptyFieldValue, DEFAULT_INDEX_FRESHNESS_INTERVAL_MS, FORCED_REFRESH_MIN_INTERVAL_MS, STALE_LOOKUP, isMissingReference, createReferenceResolveCache, ContentStore, ATTR_CONTENT, BLOCK_PREFIX, BLOCK_SUFFIX, BLOCK_RESTORE_RE, INLINE_PREFIX, INLINE_SUFFIX, INLINE_RESTORE_RE, DEFAULT_REFERENCE_RENDERING, FLAT_CELL_TYPES, log6, BASE58_CHAR, ENTRY_LINK_PATTERN, INLINE_LINK_TARGET, BranchMetadataCorruptError, BRANCH_META_DIR, BRANCH_META_FILE, branchMetadataFilePath, UNKNOWN_TIME, enumOf, branchMetadataShape, branchMetadataSchema, branchMetadataFileSchema, log7, REGISTRY_FILE, REGISTRY_STALE_FILE, REGISTRY_TEMP_FILE, REGISTRY_VERSION, RESOURCE2, GET_MISS_REFRESH_MIN_INTERVAL_MS, snapshotSchema, reportedUnreadable, BranchRegistry, log8, OccWriteConflictError, CURRENT_SCHEMA_VERSION, BranchMetadataConflictError, BranchMetadataFileManager, loadBranchContext, GitProcessError, STDERR_CAP_BYTES, KILL_GRACE_MS, log9, GIT_ENV_PASSTHROUGH, FORCE_C_LOCALE, GIT_NETWORK_ENV_PASSTHROUGH, NO_AUTO_GC_CONFIG, HASH_INACTIVITY_TIMEOUT_MS, MAX_HASH_RUNS, LS_REMOTE_INACTIVITY_TIMEOUT_MS, symlinkBlobSha, REMOTE_GIT_CONFIG, REMOTE_GIT_MAX_LOOSE_OBJECTS, REMOTE_GIT_MAX_PACKS, PARALLEL_CHECKOUT_ARGS, remoteInitLocks, GITHUB_TRACKING_REF_PREFIX, BaseBranchMissingError, GitConflictError, GitRemoteRefMissingError, RemoteNotReadyError, SettingsRemoteUnreadableError, SettingsBranchDivergedError, SETTINGS_BRANCH_FILES, SettingsBranchHasContentHistoryError, GitManager, PUBLISH_LOCK_WAIT_MS, CREATE_RESIDUE_MIN_QUIET_MS, STAGING_MAX_AGE_MS, REPAIR_MAX_AGE_MS, DELETING_MAX_AGE_MS, SETTINGS_TRASH_MAX_AGE_MS, BranchProvisioningBusyError, BranchDirOccupiedError, STAGING_PREFIX, REPAIR_PREFIX, TRASH_PREFIX, stagingDirName, NO_GIT, RENAME_BLOCKED, SPARSE_CONE_RECORD, defaultSink, sink, ProvisionLog, testHooks, provisionsInFlight, BranchWorkspaceManager, AI_USER_ID, log10, normalizePath, parseEntryParts, parseEntryData, readEntryData, createReferenceResolver, withoutUnavailableEntries, resolveCollectionItemReferences, looksLikeMalformedEntry, listCollectionEntries, MAX_INPUT_PIXELS, CROP_PRECISION, KNOWN_FIELD_TYPES, STRING_FIELD_TYPES, selectOptionValues, GENERATED_RECORD_FILENAME, SAFE_BUILD_ID, BUILD_ID_RULE, jiti;
 var init_generate_ai_content = __esm({
   "dist/cli/generate-ai-content.js"() {
     "use strict";
@@ -11170,6 +11170,8 @@ var init_generate_ai_content = __esm({
         this.code = code;
       }
     };
+    RESTORE_SLUG_TAKEN_MESSAGE = "Another entry now has this entry's URL. Change that entry's URL, then restore this one.";
+    RESTORE_ID_TAKEN_MESSAGE = "This entry is already on the branch, so there is nothing to restore. Refresh to see where it is.";
     ContentConflictError = class extends Error {
       constructor(message = "Content was modified by another editor") {
         super(message);
@@ -12014,6 +12016,65 @@ var init_generate_ai_content = __esm({
           throw new ContentConflictError();
         });
       }
+      /**
+       * Puts back an entry deleted on this branch: `raw`, its file as the base holds it, verbatim,
+       * under its old slug, entry type and content ID, so references and comment threads find it
+       * again and the branch no longer differs from the base there.
+       *
+       * A create under write()'s locks and create-only guards that never replaces or relocates
+       * anything. It refuses with `ContentConflictError` while a file holds the slug, or the index
+       * or the target directory holds the ID: unlike write(), it has no index repair, so an ID
+       * found elsewhere is a moved entry, not a deleted one, and is left alone. The index is
+       * warmed outside the lock, as write() warms it, and rescanned under the lock only when the
+       * generation marker says another host changed the tree.
+       */
+      async restore(collectionPath, slug, entry, options = {}) {
+        await this.idIndex();
+        const collection = this.assertCollection(collectionPath);
+        if (!collection.entries?.some((e) => e.name === entry.entryTypeName)) {
+          throw new ContentStoreError(`Entry type '${entry.entryTypeName}' not found in collection`, "NO_SCHEMA_ITEM");
+        }
+        this.assertEntryTypeAvailable(collection, entry.entryTypeName);
+        return this.withContentWriteExclusion(async () => {
+          await options.beforeWrite?.();
+          if (await readContentIndexGeneration(this.root) !== this.loadedDiskGeneration) {
+            this.invalidateIndex();
+          }
+          await this.idIndex();
+          return withLock(this.createLockKey(collection, slug), async () => {
+            const target = await this.buildPaths(collection, slug, {
+              existingId: entry.id,
+              entryTypeName: entry.entryTypeName
+            });
+            const dir = path112.dirname(target.absolutePath);
+            const liveIndex = this._idIndex;
+            if (liveIndex.findById(entry.id) || liveIndex.getDuplicateFor(entry.id) || (await this.findEntryPathsById(dir, entry.id)).length > 0) {
+              throw new ContentConflictError(RESTORE_ID_TAKEN_MESSAGE);
+            }
+            if ((await this.buildPaths(collection, slug)).existed) {
+              throw new ContentConflictError(RESTORE_SLUG_TAKEN_MESSAGE);
+            }
+            const routable = parseSlug(target.slug);
+            if (!routable.ok) {
+              throw new ContentStoreError(`Cannot restore entry "${target.slug}": ${routable.error}.`, "VALIDATION");
+            }
+            await this.assertUrlPathAvailable(dir, target.slug);
+            await fs9.mkdir(dir, { recursive: true });
+            await atomicWriteFile2(target.absolutePath, entry.raw);
+            const index = this._idIndex;
+            if (!index.findById(entry.id)) {
+              index.add({
+                type: "entry",
+                relativePath: target.relativePath,
+                collection: collectionPath,
+                slug
+              });
+            }
+            await this.recordOwnMutation(index);
+            return { relativePath: target.relativePath };
+          });
+        });
+      }
       /**
        * Rename an entry by changing its slug (middle segment of filename).
        * Entry filename pattern: {entryTypeName}.{slug}.{id}.{ext}

package/dist/cli/generate-ai-content.js

@@ -5325,6 +5325,8 @@ var ContentStoreError = class extends Error {
     this.code = code;
   }
 };
+var RESTORE_SLUG_TAKEN_MESSAGE = "Another entry now has this entry's URL. Change that entry's URL, then restore this one.";
+var RESTORE_ID_TAKEN_MESSAGE = "This entry is already on the branch, so there is nothing to restore. Refresh to see where it is.";
 var ContentConflictError = class extends Error {
   constructor(message = "Content was modified by another editor") {
     super(message);
@@ -6218,6 +6220,65 @@ var ContentStore = class {
       throw new ContentConflictError();
     });
   }
+  /**
+   * Puts back an entry deleted on this branch: `raw`, its file as the base holds it, verbatim,
+   * under its old slug, entry type and content ID, so references and comment threads find it
+   * again and the branch no longer differs from the base there.
+   *
+   * A create under write()'s locks and create-only guards that never replaces or relocates
+   * anything. It refuses with `ContentConflictError` while a file holds the slug, or the index
+   * or the target directory holds the ID: unlike write(), it has no index repair, so an ID
+   * found elsewhere is a moved entry, not a deleted one, and is left alone. The index is
+   * warmed outside the lock, as write() warms it, and rescanned under the lock only when the
+   * generation marker says another host changed the tree.
+   */
+  async restore(collectionPath, slug, entry, options = {}) {
+    await this.idIndex();
+    const collection = this.assertCollection(collectionPath);
+    if (!collection.entries?.some((e) => e.name === entry.entryTypeName)) {
+      throw new ContentStoreError(`Entry type '${entry.entryTypeName}' not found in collection`, "NO_SCHEMA_ITEM");
+    }
+    this.assertEntryTypeAvailable(collection, entry.entryTypeName);
+    return this.withContentWriteExclusion(async () => {
+      await options.beforeWrite?.();
+      if (await readContentIndexGeneration(this.root) !== this.loadedDiskGeneration) {
+        this.invalidateIndex();
+      }
+      await this.idIndex();
+      return withLock(this.createLockKey(collection, slug), async () => {
+        const target = await this.buildPaths(collection, slug, {
+          existingId: entry.id,
+          entryTypeName: entry.entryTypeName
+        });
+        const dir = path11.dirname(target.absolutePath);
+        const liveIndex = this._idIndex;
+        if (liveIndex.findById(entry.id) || liveIndex.getDuplicateFor(entry.id) || (await this.findEntryPathsById(dir, entry.id)).length > 0) {
+          throw new ContentConflictError(RESTORE_ID_TAKEN_MESSAGE);
+        }
+        if ((await this.buildPaths(collection, slug)).existed) {
+          throw new ContentConflictError(RESTORE_SLUG_TAKEN_MESSAGE);
+        }
+        const routable = parseSlug(target.slug);
+        if (!routable.ok) {
+          throw new ContentStoreError(`Cannot restore entry "${target.slug}": ${routable.error}.`, "VALIDATION");
+        }
+        await this.assertUrlPathAvailable(dir, target.slug);
+        await fs9.mkdir(dir, { recursive: true });
+        await atomicWriteFile(target.absolutePath, entry.raw);
+        const index = this._idIndex;
+        if (!index.findById(entry.id)) {
+          index.add({
+            type: "entry",
+            relativePath: target.relativePath,
+            collection: collectionPath,
+            slug
+          });
+        }
+        await this.recordOwnMutation(index);
+        return { relativePath: target.relativePath };
+      });
+    });
+  }
   /**
    * Rename an entry by changing its slug (middle segment of filename).
    * Entry filename pattern: {entryTypeName}.{slug}.{id}.{ext}

package/dist/content-store.d.ts

@@ -43,6 +43,10 @@ export declare class ContentStoreError extends Error {
     code: ContentStoreErrorCode;
     constructor(message: string, code: ContentStoreErrorCode);
 }
+/** Why a restore refuses: another entry took the slug after this one was deleted. */
+export declare const RESTORE_SLUG_TAKEN_MESSAGE = "Another entry now has this entry's URL. Change that entry's URL, then restore this one.";
+/** Why a restore refuses: the entry, by its content ID, is on the branch already. */
+export declare const RESTORE_ID_TAKEN_MESSAGE = "This entry is already on the branch, so there is nothing to restore. Refresh to see where it is.";
 /**
  * Thrown when `expectedVersion` on a write doesn't match the file's current mtime.
  * Indicates a cross-process concurrent write — the caller should reload and retry.
@@ -480,6 +484,28 @@ export declare class ContentStore {
     protected afterPrePassForTesting(): Promise<void>;
     /** Delete an entry and remove it from the index. */
     delete(collectionPath: LogicalPath, slug: Slug): Promise<void>;
+    /**
+     * Puts back an entry deleted on this branch: `raw`, its file as the base holds it, verbatim,
+     * under its old slug, entry type and content ID, so references and comment threads find it
+     * again and the branch no longer differs from the base there.
+     *
+     * A create under write()'s locks and create-only guards that never replaces or relocates
+     * anything. It refuses with `ContentConflictError` while a file holds the slug, or the index
+     * or the target directory holds the ID: unlike write(), it has no index repair, so an ID
+     * found elsewhere is a moved entry, not a deleted one, and is left alone. The index is
+     * warmed outside the lock, as write() warms it, and rescanned under the lock only when the
+     * generation marker says another host changed the tree.
+     */
+    restore(collectionPath: LogicalPath, slug: Slug, entry: {
+        id: ContentId;
+        entryTypeName: string;
+        raw: string;
+    }, options?: {
+        /** Runs under the content-write lock before anything is written; throwing refuses. */
+        beforeWrite?: () => Promise<void>;
+    }): Promise<{
+        relativePath: PhysicalPath;
+    }>;
     /**
      * Rename an entry by changing its slug (middle segment of filename).
      * Entry filename pattern: {entryTypeName}.{slug}.{id}.{ext}