@acms-subir/core 0.3.16 → 0.3.17

package/docs/environment-sync.md

@@ -0,0 +1,302 @@
+# Selective environment sync
+
+Use `acms sync` to transfer selected native ACMS content between two running
+sites. Both directions work: local → production, production → local, or staging
+→ production. Both sites must run a version that includes sync protocol 1.
+Run `acms sync --help` for the command reference or `acms docs sync` to read
+this guide from an installed package.
+
+This transfers content and portable configuration, not application code,
+database schemas, environment variables, or an entire database. Deploy theme
+code, collection definitions and enabled modules through the application's
+normal deployment process first. Secrets remain in each environment's own
+Infisical project/environment/folder. Backups remain the disaster recovery tool.
+
+## Connect and choose a direction
+
+An owner creates scoped keys under **Design → Access**. The existing design-key
+screen also offers these permissions:
+
+| Scope | Permission |
+| --- | --- |
+| `sync:read` | Read the portable inventory, drafts, media and transfer history |
+| `sync:write` | Create plans, upload media and apply draft transfers; also needs `sync:read` |
+| `sync:publish` | Apply live, publication and rollback plans; also needs both scopes above |
+
+Only an owner can issue sync keys. Existing design, agent and booking keys do
+not implicitly grant sync access. For a one-way transfer, the source needs
+read access and the destination needs read/write (plus publish for live work).
+Reverse transfers need the corresponding permissions in the other direction.
+
+Supply the keys privately through the named environment variables, preferably
+using the CLI's existing Infisical runtime-injection setup. Do not place tokens
+in command arguments, plan files, source control, or chat.
+
+```sh
+acms site connect http://localhost:4321 --site local --token-env ACMS_LOCAL_TOKEN
+acms site connect https://example.com --site production --token-env ACMS_PRODUCTION_TOKEN
+acms sync init --from local --to production
+```
+
+`site connect` is an existing command. It stores the URL and environment-variable
+name, not the credential. Remote sites require HTTPS; loopback HTTP is allowed.
+Sync accesses each site's authenticated HTTP API, so the CLI needs network
+access to both sites. It does not open a production database directly.
+
+`init` selects a direction and resumes that pair's saved selection. It does not
+transfer content. Switching directions keeps separate selections and baselines:
+
+```sh
+acms sync init --from production --to local
+```
+
+The CLI binds the pair to installation identities as well as URLs. A changed
+profile URL or replaced installation requires a fresh `init`. Two aliases for
+the same installation cannot be synchronized to each other. Cloning the entire
+database also clones its installation identity; use independent installations
+and content transfers rather than using a database clone as a second sync site.
+
+## Inspect and select
+
+```sh
+acms sync status
+acms sync status --type pages
+acms sync status --selected
+acms sync status --conflicts
+acms sync list
+acms sync list --type events --calendar community
+acms sync list --search welcome
+```
+
+Status distinguishes create, update, skip, preserve and conflict. The inventory
+shows references and stable keys. Use the full key when names are ambiguous.
+Posts accept `post:<collection>/<slug>`; `post:<slug>` also works when unique.
+Forms and places have names rather than slugs, so quote references containing
+spaces, such as `'form:Contact us'`.
+
+```sh
+acms sync add page:home page:about
+acms sync add post:posts/welcome
+acms sync add event:open-house
+acms sync add resource:meeting-room
+acms sync add 'form:Contact us'
+acms sync add calendar:community --include-events
+acms sync add --type navigation
+acms sync add --type booking-config
+acms sync add --all
+```
+
+`add --all` selects eligible changed source items, including conflicts for
+review. It never selects customer bookings, submissions, account credentials,
+secrets or deletions. `add --type` selects changed items in that category.
+Selecting a calendar alone does not select all its events; `--include-events`
+does. Selected events include the calendars and other referenced objects they
+need. Pages include referenced media and native ID-based dependencies. Links
+to arbitrary URLs are not crawled or copied.
+
+`acms sync select` is a terminal picker: it displays numbered items and accepts
+a comma-separated selection. Blank input preserves the selection. Explicit
+commands provide the equivalent workflow for scripts; interactive mode cannot
+be combined with `--json`.
+
+```sh
+acms sync remove page:test-landing
+acms sync remove --type events
+acms sync clear
+```
+
+Removing items only changes the pending selection. An explicitly removed
+dependency blocks its parent rather than silently reselecting it. Add the
+dependency again, preserve an existing destination version, or remove the parent.
+`clear` clears selections, exclusions and conflict decisions, not history or
+the last successful synchronization baseline.
+
+## Review differences and conflicts
+
+```sh
+acms sync diff
+acms sync diff page:home
+acms sync diff --selected
+acms sync resolve page:home --use source
+acms sync resolve page:home --use destination
+acms sync resolve page:home --interactive
+```
+
+Diff shows actual before/after field values. The source inventory includes
+saved pending drafts as the editable source version; it does not capture
+unsaved browser edits. Live versus draft behavior on the destination is chosen
+when planning.
+
+The CLI remembers the last successfully applied source and destination hashes:
+
+| Comparison | Default action |
+| --- | --- |
+| Same content on both sites | Skip |
+| Only the source changed since the baseline | Update |
+| Only the destination changed | Preserve destination |
+| Both changed differently | Conflict |
+| Existing item with no established baseline | Review before overwrite |
+| Previously transferred item deleted on destination | Conflict |
+| Item exists only on destination | Preserve |
+
+Matching uses recorded identities first. A unique natural-key candidate
+(such as a collection and slug) can be proposed for the initial match, but a
+differing existing item requires explicit resolution. Ambiguous names are
+blocked; fix ambiguity on the destination first. Slug changes keep an established
+identity. Sync does not automatically create redirects for renamed URLs;
+select the appropriate redirect records as well.
+
+`--use source` approves the source version; `--use destination` leaves the
+destination content intact. If a previously transferred item was deleted on
+the destination, `--use source` explicitly approves recreating it. Required
+preserved dependencies are linked without overwriting their data. Interactive
+resolution chooses whole top-level fields;
+it is not a text-editor or automatic rich-text/array merge. Conflict decisions
+are tied to the reviewed source and destination versions and expire when either
+changes. There is no `--force` bypass.
+
+## Plan, apply and publish
+
+```sh
+acms sync plan
+acms sync plan --mode draft --out deployment-plan.json
+acms sync plan --mode live
+acms sync show <plan-id>
+acms sync apply --plan <plan-id>
+acms sync apply --file deployment-plan.json
+```
+
+Draft is the default. Pages, posts, events, forms and design support draft
+transfers. New draft-capable records are created unpublished; existing live
+content retains its live version while changes are staged. New required media
+and tag records are added to their libraries. Updating existing media/tag
+metadata and transferring navigation, calendars, resources, booking links,
+places, redirects or portable settings requires an explicit live plan. A
+published form's definition can be staged; its name/kind/purpose changes need
+a live plan. An event with room holds must have those configured on the
+destination after transfer.
+
+Plans list selected operations, dependencies, field differences and whether
+changes affect drafts or live content. They are stored on the destination and
+bound to its installation ID, revision and exact payload. Planning changes
+transfer metadata only, never site content. Exported files include a human-
+readable copy, source/destination binding and a digest; editing their payload
+does not alter the immutable server plan. Create a new plan to change it.
+
+Apply displays the plan and asks for confirmation. Automation uses:
+
+```sh
+acms sync apply --plan <plan-id> --yes --json
+```
+
+`--yes` skips only the confirmation. It cannot bypass scopes, dependencies,
+schema/theme compatibility, conflicts or stale revisions. Apply does not need
+the current selection to match the saved plan; it applies that exact plan.
+
+The database checks the reviewed revision inside the same transaction as all
+record writes, identity links, search-index changes and the completed-run
+receipt. Content/draft changes through other APIs also advance the revision.
+The first implementation uses a conservative **site-wide revision**: unrelated
+content edits or booking/submission activity after planning can require a new
+plan too. This favors rejecting stale plans over overwriting concurrent work.
+
+Media is uploaded before that transaction to immutable checksum-based keys.
+Already present verified objects are skipped. Failed uploads or a rejected
+database transaction can leave unused files, but do not partially publish the
+database changes. Sync does not delete these files automatically.
+
+If a request or terminal is interrupted, rerun the same apply command. A
+completed server receipt is returned without repeating writes; otherwise
+verified files are reused and the database transaction can be retried if the
+reviewed revision still matches. There is no blind retry of stale writes.
+
+After reviewing staged content in the site's editors/previews:
+
+```sh
+acms sync plan --publish <run-id>
+acms sync apply --plan <publish-plan-id>
+```
+
+This publishes only the draft-capable items in that run. It rejects later edits
+to those items instead of implicitly publishing somebody else's changes.
+Design/layout changes conservatively share a settings guard.
+
+## History and rollback
+
+```sh
+acms sync history
+acms sync show <run-id>
+acms sync plan --rollback <run-id>
+acms sync apply --plan <rollback-plan-id>
+```
+
+History lists the latest 100 plans and runs. An older known ID can still be
+read with `show`. Rollback creates another reviewable live plan. It restores
+previous live/draft values for changed items and can delete items that the run
+created, provided they have not subsequently changed or acquired dependents or
+production activity. Media bytes are retained, even if their newly created
+library record is removed. Later design/settings edits may conservatively block
+rollback of a page layout. Rollback does not undo delivered emails, webhook
+deliveries, external effects or code deployments.
+
+## Transfer coverage
+
+| Category | Included | Environment-specific data preserved |
+| --- | --- | --- |
+| `pages` | Native rich text, legacy blocks, translations, layout, SEO and routing fields | Unselected pages |
+| `posts` | Native content, translations, metadata and byline references | Staff credentials and account authority |
+| `design` | Theme selection, design overrides and branding images | Theme source code; page layouts travel with pages |
+| `navigation` | Individual navigation records | Other destination navigation records |
+| `media` | Metadata, originals and variants, with checksums | Unselected assets |
+| `redirects` | Selected redirect records | Other destination redirects |
+| `calendars` | Calendar definitions | Feed tokens and source URLs |
+| `events` | Native events and registration-form definitions | Registrations and notification history |
+| `resources` | Resource configuration | Private busy-feed URLs, notification recipients and feed tokens |
+| `booking-config` | Booking-link definitions and calendar/booking defaults | Reservations, retry ledgers and private management links |
+| `forms` | Definitions/templates, native drafts | Submitted responses |
+| `site-settings` | Title, tagline, footer text, locale, timezone, announcement | Canonical site URL, integration/analytics configuration, injected code, secrets |
+| `places` | Saved place definitions | Other saved places |
+| `tags` | Tag metadata | Other tag records |
+
+Byline dependencies map to existing destination profiles. Sync never creates
+or edits user accounts; provision the intended profile separately and preserve
+its destination version when appropriate. Feed calendars must already exist
+on the destination with their own configured URL. Calendar and booking modules,
+post collections, theme code and section definitions must be deployed before
+their associated content can be applied.
+
+Events with existing destination reservations and resources with active
+reservations cannot be overwritten through sync. Use the destination editor
+for those operational changes. Bookings and submissions created after review
+invalidate the plan; rollback also checks for activity before deleting items.
+
+## Automation, storage and limits
+
+- `--json` returns the existing `acms.cli/1` envelope; exit 4 denotes conflicts,
+  3 authentication/permission failures, 5 network/server failures, and 2 invalid
+  usage/input. Diagnostics and interactive prompts use stderr.
+- `--dry-run` on selection commands does not save selection changes. On a
+  normal plan it asks the server to validate without storing a plan; on apply
+  it displays the saved plan without uploading or applying. Publication and
+  rollback plans are also validated without storing them in dry-run mode.
+- `--cwd <project>` chooses the project workspace. Selection, baselines and
+  exported-plan references are stored under
+  `${ACMS_CONFIG_DIR:-~/.config/acms}/sync/<workspace-hash>/`, with private file
+  permissions. They are not committed into the project. Exported plan files
+  contain unpublished content and should be kept out of source control.
+- A workspace lock prevents simultaneous CLI commands from losing selections.
+  After a crashed CLI process, verify that the PID in the reported lock file
+  is no longer running before removing that file.
+- Protocol 1 supports up to 2,000 inventory items, an 8 MiB inventory, 200
+  selected operations per plan and 16 MiB per media object. Oversized inputs
+  fail explicitly; split selections where possible. The inventory is bounded
+  rather than silently truncated. This version hashes media during inventory
+  reads; large media libraries may need a future paginated/cached inventory.
+  Hosting-platform request, subrequest and CPU limits can impose lower practical
+  limits; local D1 tests do not establish a live Cloudflare account's limits.
+- Sync history lives on the destination; it is not part of portable content
+  backups. Sync does not promise a cross-resource transaction with object
+  storage. Keep normal off-site backups and test disaster recovery separately.
+
+There is no automatic deletion propagation, background two-way synchronization,
+stash command, automatic text merge, or full database transfer.

package/integration.mjs

@@ -87,6 +87,8 @@ const ROUTES = [
   ['/api/ai/clean', 'api/ai/clean.ts'],
   ['/api/ai/draft', 'api/ai/draft.ts'],
   ['/api/design', 'api/design/index.ts'],
+  ['/api/sync', 'api/sync/index.ts'],
+  ['/api/sync/media', 'api/sync/media.ts'],
   ['/api/design/keys', 'api/design/keys.ts'],
   ['/api/design/capabilities', 'api/design/capabilities.ts'],
   ['/api/design/media', 'api/design/media.ts'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acms-subir/core",
-  "version": "0.3.16",
+  "version": "0.3.17",
   "publishConfig": {
     "access": "public"
   },

package/src/components/DesignAccess.tsx

@@ -12,6 +12,9 @@ const SCOPES: { key: string; label: string; hint: string }[] = [
   { key: 'design:publish', label: 'Publish design', hint: 'Makes the draft live for visitors. Only grant this to tools you trust' },
   { key: 'media:read', label: 'Read media', hint: 'Browse the media library' },
   { key: 'media:write', label: 'Upload media', hint: 'Add images to the media library' },
+  { key: 'sync:read', label: 'Read environment content', hint: 'Read portable content, media and sync history, including drafts' },
+  { key: 'sync:write', label: 'Stage environment transfers', hint: 'Create plans, upload assets and apply draft transfers; also needs Read environment content' },
+  { key: 'sync:publish', label: 'Apply live environment transfers', hint: 'Publish content and apply reviewed live or rollback plans; also needs both sync permissions above' },
 ];
 const DEFAULT_SCOPES = ['design:read', 'design:write-draft'];
 

package/src/lib/repo/migrations.ts

@@ -7,6 +7,7 @@ import { EDITOR_MIGRATION, EDITOR_GRACE_MIGRATION } from '../editor/migration';
 import { CALENDAR_SETTINGS_MIGRATION, ROOM_HOLD_MIGRATION } from '../calendar/migration';
 import { PLACES_MIGRATION } from '../maps/migration';
 import { ROLES_MIGRATION } from '../permissions/migration';
+import { SYNC_MIGRATION } from '../sync/migration';
 // Versioned schema migrations shared by the two SQLite-dialect adapters
 // (D1 and libSQL). Applied versions are recorded in the `migrations` table;
 // each adapter's runner applies whatever is newer, in order, at startup.
@@ -632,6 +633,7 @@ export const MIGRATIONS: Migration[] = [
     `INSERT INTO backup_state (id) VALUES (1)`,
   ] },
   ROLES_MIGRATION,
+  SYNC_MIGRATION,
 ];
 
 export const LATEST_VERSION = MIGRATIONS[MIGRATIONS.length - 1].version;

package/src/lib/repo/sql.ts

@@ -1,4 +1,5 @@
 import { AUTH } from '../auth/config';
+import { SyncStore } from '../sync/store';
 import { AuthStore } from '../auth/store';
 import { FormStore, formInsert, submissionInsert } from '../forms/store';
 import { GuestStore } from '../mobile/guest-store';
@@ -260,6 +261,7 @@ function safeSnippet(raw: unknown): string {
 }
 
 export class SqlRepository implements ContentRepository {
+  readonly sync: SyncStore;
   private driver!: SqlDriver;
   private ready: Promise<void>;
   readonly auth: AuthStore;
@@ -274,6 +276,7 @@ export class SqlRepository implements ContentRepository {
 
   constructor(driver: SqlDriver | (() => Promise<SqlDriver>)) {
     this.ready = this.init(driver);
+    this.sync = new SyncStore(async () => { await this.ready; return this.driver; });
     this.forms = new FormStore(async () => { await this.ready; return this.driver; });
     this.guests = new GuestStore(async () => { await this.ready; return this.driver; });
     this.live = new LiveStore(async () => { await this.ready; return this.driver; });

package/src/lib/repo/types.ts

@@ -1,4 +1,5 @@
 import { AuthStore } from '../auth/store';
+import type { SyncStore } from '../sync/store';
 import type { FormStore } from '../forms/store';
 import type { BackupStore } from '../backup/store';
 import type { GuestStore } from '../mobile/guest-store';
@@ -53,6 +54,7 @@ export type EventUpdate = Partial<
 // The single contract both backends implement. The app only ever imports
 // this — never a concrete adapter.
 export interface ContentRepository {
+  readonly sync: SyncStore;
   readonly auth: AuthStore;
   readonly email: EmailStore;
   readonly forms: FormStore;

package/src/lib/schema.ts

@@ -637,6 +637,7 @@ export const API_SCOPES = [
   'bookings:read', 'bookings:write',
   'resources:read', 'resources:write',
   'design:read', 'design:write-draft', 'design:publish', 'media:read', 'media:write',
+  'sync:read', 'sync:write', 'sync:publish',
 ] as const;
 export const ApiScope = z.enum(API_SCOPES);
 export type ApiScope = z.infer<typeof ApiScope>;

package/src/lib/sync/auth.ts

@@ -0,0 +1,24 @@
+import { ApiError } from "../api";
+import { hashAgentKey } from "../ai-config";
+import type { ContentRepository } from "../repo/types";
+export const SYNC_SCOPES = ["sync:read", "sync:write", "sync:publish"] as const;
+export async function syncIdentity(
+  request: Request,
+  repo: ContentRepository,
+  required: readonly string[],
+) {
+  const origin = request.headers.get("origin");
+  if (
+    request.headers.get("sec-fetch-site") === "cross-site" ||
+    (origin && origin !== new URL(request.url).origin)
+  )
+    throw new ApiError(403, "Cross-origin sync requests are not allowed.");
+  const header = request.headers.get("authorization") ?? "";
+  if (!header.startsWith("Bearer "))
+    throw new ApiError(401, "Use a scoped sync key.");
+  const key = await repo.findApiKeyByHash(hashAgentKey(header.slice(7)));
+  if (!key) throw new ApiError(401, "Invalid sync key.");
+  if (required.some((s) => !key.scopes.includes(s as any)))
+    throw new ApiError(403, `Required scopes: ${required.join(", ")}`);
+  return { actor: `key:${key.id}`, scopes: key.scopes };
+}

package/src/lib/sync/catalog.ts

@@ -0,0 +1,250 @@
+import { z } from "zod";
+import {
+  Page,
+  Post,
+  Calendar,
+  CalEvent,
+  Resource,
+  BookingLink,
+  Place,
+  Media,
+  NavItem,
+  Redirect,
+  Tag,
+  Settings,
+  CalendarSettings,
+} from "../schema";
+import { SavedForm } from "../forms/schema";
+import { DesignPatch } from "../design-service";
+import { SectionPages } from "../../theme-sdk/contract.mjs";
+import { pickPageDraft, pickPostDraft, pickEventDraft } from "../drafts";
+import { ApiError } from "../api";
+
+export type Data = Record<string, any>;
+const common = { id: true, createdAt: true, updatedAt: true } as const;
+export const schemas = {
+  page: Page.omit({ ...common, draft: true })
+    .extend({ layout: z.unknown().nullable() })
+    .strict(),
+  post: Post.omit({ ...common, draft: true, authorId: true }).strict(),
+  calendar: Calendar.omit({
+    ...common,
+    feedToken: true,
+    feedUrl: true,
+  }).strict(),
+  event: CalEvent.omit({
+    ...common,
+    draft: true,
+    startAt: true,
+    endAt: true,
+    sourceUid: true,
+  }).strict(),
+  resource: Resource.omit({
+    ...common,
+    feedToken: true,
+    busyFeeds: true,
+    notifyEmails: true,
+  }).strict(),
+  booking: BookingLink.omit(common).strict(),
+  place: Place.omit(common).strict(),
+  form: SavedForm.omit({ ...common, draft: true, revision: true }).strict(),
+  media: Media.omit({ id: true, createdAt: true })
+    .extend({
+      objects: z
+        .array(
+          z
+            .object({
+              key: z.string(),
+              digest: z.string().regex(/^[a-f0-9]{64}$/),
+              size: z.number().int().nonnegative(),
+            })
+            .strict(),
+        )
+        .max(20),
+    })
+    .strict(),
+  nav: NavItem.omit({ id: true }).strict(),
+  redirect: Redirect.omit({ id: true, createdAt: true }).strict(),
+  tag: Tag.omit({ id: true }).strict(),
+  design: DesignPatch.omit({ sectionPages: true, navItems: true }).strict(),
+  settings: Settings.pick({
+    siteTitle: true,
+    tagline: true,
+    footerText: true,
+    timezone: true,
+    locale: true,
+    announcement: true,
+  }).strict(),
+  "booking-settings": CalendarSettings.strict(),
+  // Bylines can be linked to existing profiles; accounts never transfer.
+  author: z.object({ name: z.string(), slug: z.string() }).strict(),
+};
+export type Kind = keyof typeof schemas;
+export const tables: Partial<Record<Kind, string>> = {
+  page: "pages",
+  post: "posts",
+  calendar: "calendars",
+  event: "events",
+  resource: "resources",
+  booking: "booking_links",
+  place: "places",
+  form: "forms",
+  media: "media",
+  nav: "nav_items",
+  redirect: "redirects",
+  tag: "tags",
+  author: "users",
+};
+export const settingsKinds = new Set<Kind>([
+  "design",
+  "settings",
+  "booking-settings",
+]);
+export const draftKinds = new Set<Kind>([
+  "page",
+  "post",
+  "event",
+  "form",
+  "design",
+]);
+const special: Record<string, string> = {
+  order: "ord",
+  start: "starts",
+  end: "ends",
+};
+export const column = (field: string) =>
+  special[field] ?? field.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+const jsonFields = new Set([
+  "blocks",
+  "translations",
+  "tags",
+  "calendarIds",
+  "fields",
+  "location",
+  "cta",
+  "rsvp",
+  "roomHold",
+  "exdates",
+  "amenities",
+  "hours",
+  "overrides",
+  "lengths",
+  "approvalRules",
+  "questions",
+  "variants",
+  "definition",
+  "designOverrides",
+  "announcement",
+]);
+const boolFields = new Set([
+  "isHome",
+  "featured",
+  "allDay",
+  "cancelled",
+  "showOnCalendar",
+  "isDefault",
+  "autoConfirm",
+  "askPhone",
+  "active",
+]);
+export function fields(kind: Kind) {
+  return Object.keys(schemas[kind].shape).filter(
+    (k) => !["layout", "objects", "authorIds"].includes(k),
+  );
+}
+export const encode = (value: any) =>
+  value === null
+    ? null
+    : typeof value === "boolean"
+      ? Number(value)
+      : typeof value === "object"
+        ? JSON.stringify(value)
+        : value;
+export function rowData(kind: Kind, row: Data): Data {
+  const data: Data = {};
+  for (const key of fields(kind)) {
+    let value = row[column(key)];
+    if (value === undefined) continue;
+    if (jsonFields.has(key) && typeof value === "string")
+      value = JSON.parse(value);
+    if (boolFields.has(key)) value = Boolean(value);
+    data[key] = value;
+  }
+  return data;
+}
+export function parseData(kind: Kind, input: unknown): Data {
+  const data = schemas[kind].parse(input) as Data;
+  if (kind === "page" && data.layout !== null)
+    SectionPages.parse({ page: data.layout });
+  if (
+    ["page", "post", "calendar", "event", "resource", "booking"].includes(
+      kind,
+    ) &&
+    !/^[a-z0-9][a-z0-9-]{0,199}$/.test(data.slug)
+  )
+    throw new ApiError(400, "Sync requires a valid content slug.");
+  if (kind === "media") {
+    for (const key of [
+      data.key,
+      ...data.variants.map((v: Data) => v.key),
+      ...data.objects.map((o: Data) => o.key),
+    ])
+      safeMediaKey(key);
+    const required = [data.key, ...data.variants.map((v: Data) => v.key)];
+    if (
+      data.objects.length !== required.length ||
+      required.some(
+        (k) => data.objects.filter((o: Data) => o.key === k).length !== 1,
+      )
+    )
+      throw new ApiError(
+        400,
+        "Media checksums must cover each file exactly once.",
+      );
+  }
+  return data;
+}
+export function safeMediaKey(key: string) {
+  if (
+    !/^[a-zA-Z0-9_./-]+$/.test(key) ||
+    key.startsWith("/") ||
+    key.split("/").some((p) => !p || p === "." || p === "..") ||
+    key.length > 500
+  )
+    throw new ApiError(400, "Invalid media storage key.");
+  return key;
+}
+export function effective(kind: Kind, live: Data, draft: Data | null): Data {
+  if (!draft) return live;
+  const pick =
+    kind === "page"
+      ? pickPageDraft
+      : kind === "post"
+        ? pickPostDraft
+        : kind === "event"
+          ? pickEventDraft
+          : null;
+  if (pick) return { ...live, ...pick(draft) };
+  if (kind === "form") return { ...live, definition: draft };
+  if (kind === "design")
+    return {
+      ...live,
+      ...Object.fromEntries(
+        Object.entries(draft).filter(([k]) => fields("design").includes(k)),
+      ),
+    };
+  return live;
+}
+export function matchKey(kind: Kind, data: Data) {
+  if (kind === "post") return `${data.collection}/${data.slug}`;
+  if (kind === "booking") return `${data.resourceId}/${data.slug}`;
+  if (kind === "nav") return `${data.area}/${data.url}`;
+  if (kind === "redirect") return data.fromPath;
+  if (kind === "media") return data.objects?.[0]?.digest ?? data.key;
+  return data.slug || data.name || kind;
+}
+export function displayRef(kind: Kind, data: Data) {
+  if (settingsKinds.has(kind)) return `${kind}:site`;
+  if (kind === "post") return `post:${data.collection}/${data.slug}`;
+  return `${kind}:${data.slug || data.name || data.filename || data.fromPath || data.label}`;
+}