@acms-subir/core 0.3.16 → 0.3.18

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.18",
   "publishConfig": {
     "access": "public"
   },

package/section-library/upcoming-events/UpcomingEvents.astro

@@ -1,9 +1,12 @@
 ---
+import { eventImage } from '@acms-subir/core/theme';
 import type { SectionProps, EventItem, LinkValue } from '@acms-subir/core/theme';
-interface Data { heading: string; intro: string; events: EventItem[]; more: LinkValue; empty: string }
-const { data, variant } = Astro.props as SectionProps<Data>;
+interface Data { heading: string; intro: string; events: EventItem[]; more: LinkValue; empty: string; fallbackImage: string; showImages: boolean; imageRatio: string; imageFit: string; showLocation: boolean; showSummary: boolean }
+const { data, variant, settings } = Astro.props as SectionProps<Data>;
+const ratio = ({ landscape: '16 / 9', square: '1', portrait: '3 / 4' } as Record<string, string>)[data.imageRatio] || '16 / 9';
+const fit = data.imageFit === 'contain' ? 'contain' : 'cover';
 ---
-<div class:list={['upev', `is-${variant}`]}>
+<div style={`--event-image-ratio:${ratio};--event-image-fit:${fit}`} class:list={['upev', `is-${variant}`]}>
   <header class="upev-head">
     <div>
       <h2>{data.heading}</h2>
@@ -13,18 +16,22 @@ const { data, variant } = Astro.props as SectionProps<Data>;
   </header>
   {data.events.length === 0 ? <p class="upev-empty">{data.empty}</p> : (
     <ol class="upev-list">
-      {data.events.map((e) => (
-        <li class:list={['upev-item', { 'is-cancelled': e.cancelled }]}>
-          {variant === 'cards' && e.image
-            ? <a class="upev-media" href={e.url} tabindex="-1" aria-hidden="true"><img src={e.image} alt="" loading="lazy" /></a>
-            : <span class="upev-date" aria-hidden="true"><b>{e.day}</b>{e.month}</span>}
-          <div class="upev-body">
-            <span class="upev-when">{e.cancelled ? 'Cancelled · ' : ''}{e.when}</span>
-            <h3 class="upev-title"><a href={e.url}>{e.title}</a></h3>
-            {e.location && <span class="upev-loc">{e.location}</span>}
-          </div>
-        </li>
-      ))}
+      {data.events.map((e) => {
+        const image = eventImage({ cover: e.image, coverAlt: e.imageAlt }, settings, data.fallbackImage);
+        return (
+          <li class:list={['upev-item', { 'is-cancelled': e.cancelled }]}>
+            {data.showImages !== false && image.src
+              ? <a class="upev-media" href={e.url} tabindex="-1" aria-hidden="true"><img src={image.src} alt="" loading="lazy" /></a>
+              : <span class="upev-date" aria-hidden="true"><b>{e.day}</b>{e.month}</span>}
+            <div class="upev-body">
+              <span class="upev-when">{e.cancelled ? 'Cancelled · ' : ''}{e.when}</span>
+              <h3 class="upev-title"><a href={e.url}>{e.title}</a></h3>
+              {data.showSummary && e.summary && <p class="upev-summary">{e.summary}</p>}
+              {data.showLocation !== false && e.location && <span class="upev-loc">{e.location}</span>}
+            </div>
+          </li>
+        );
+      })}
     </ol>
   )}
 </div>
@@ -40,8 +47,10 @@ const { data, variant } = Astro.props as SectionProps<Data>;
   .upev-item { display: flex; gap: 1rem; align-items: flex-start; }
   .is-cards .upev-item { flex-direction: column; padding: 1rem; background: var(--panel); border: 1px solid var(--line); border-radius: var(--r); }
   .is-list .upev-item { padding-bottom: 1rem; border-bottom: 1px solid var(--line); }
-  .upev-media { display: block; width: 100%; aspect-ratio: 16 / 9; border-radius: var(--r-sm); overflow: hidden; background: var(--soft); }
-  .upev-media img { width: 100%; height: 100%; object-fit: cover; }
+  .upev-media { display: block; width: 100%; aspect-ratio: var(--event-image-ratio); border-radius: var(--r-sm); overflow: hidden; background: var(--soft); }
+  .upev-media img { width: 100%; height: 100%; object-fit: var(--event-image-fit); }
+  .is-list .upev-media { width: 6rem; flex: 0 0 6rem; }
+  .upev-summary { margin: 0.4rem 0 0; color: var(--muted); }
   .upev-date { flex-shrink: 0; display: grid; place-items: center; width: 3.4rem; padding: 0.45rem 0; border-radius: var(--r-sm); background: var(--ink); color: var(--bg); font-size: 0.7rem; font-weight: 600; letter-spacing: 0.06em; line-height: 1.2; }
   .upev-date b { font-size: 1.35rem; letter-spacing: 0; }
   .upev-body { display: flex; flex-direction: column; gap: 0.2rem; min-width: 0; }

package/section-library/upcoming-events/section.json

@@ -40,6 +40,47 @@
         "label": "Text when nothing is scheduled",
         "type": "text",
         "default": "Nothing scheduled right now. Check back soon."
+      },
+      "fallbackImage": {
+        "label": "Fallback event image",
+        "type": "image",
+        "default": "",
+        "help": "Used only when an event has no image. Leave empty to use the fallback in Calendar settings."
+      },
+      "showImages": {
+        "label": "Show event images",
+        "type": "toggle",
+        "default": true
+      },
+      "imageRatio": {
+        "label": "Image proportions",
+        "type": "select",
+        "options": [
+          "landscape",
+          "square",
+          "portrait"
+        ],
+        "default": "landscape"
+      },
+      "imageFit": {
+        "label": "Image fit",
+        "type": "select",
+        "options": [
+          "cover",
+          "contain"
+        ],
+        "default": "cover",
+        "help": "Cover fills the frame; contain shows the whole image."
+      },
+      "showLocation": {
+        "label": "Show event location",
+        "type": "toggle",
+        "default": true
+      },
+      "showSummary": {
+        "label": "Show event summary",
+        "type": "toggle",
+        "default": false
       }
     },
     "category": "Events & times"

package/src/actions/index.ts

@@ -10,7 +10,7 @@ import { getMediaStore } from '../lib/media/store';
 import { validateRequestSession } from '../lib/auth/request';
 import { accessFor } from '../lib/permissions/access';
 import { deniedMessage, type Permission } from '../lib/permissions/catalog';
-import { DocTranslations, LinkKind, parseConfig, slugify, widgetTypes, type WidgetType } from '../lib/schema';
+import { DocTranslations, LinksAvatarShape, LinksAvatarFit, LinksAvatarScale, LinkKind, parseConfig, slugify, widgetTypes, type WidgetType } from '../lib/schema';
 import { env } from '../lib/env';
 import { CONTENT, collectionUrl } from '../lib/content';
 import { invalidateRedirectCache } from '../middleware';
@@ -489,6 +489,10 @@ export const server = {
         linksName: z.string().optional(),
         linksBio: z.string().optional(),
         linksAvatar: z.string().optional(),
+        linksAvatarShape: LinksAvatarShape.optional(),
+        linksAvatarFit: LinksAvatarFit.optional(),
+        linksAvatarScale: LinksAvatarScale.optional(),
+        linksVerified: z.boolean().optional(),
         activeTheme: z.string().optional(),
         designOverrides: z.record(z.any()).optional(),
         siteLogo: z.string().optional(),

package/src/components/CalendarFallbackImage.tsx

@@ -0,0 +1,18 @@
+import { useState } from 'react';
+import { ImagePicker } from './editor/ImagePicker';
+
+export default function CalendarFallbackImage({ value, unsplashEnabled }: { value: string; unsplashEnabled: boolean }) {
+  const [image, setImage] = useState(value);
+  const [open, setOpen] = useState(false);
+  return (
+    <div>
+      <input type="hidden" name="eventFallbackImage" value={image} />
+      {image && <img src={image} alt="Selected fallback event image" style={{ display: 'block', width: '100%', maxWidth: 320, aspectRatio: '16 / 9', objectFit: 'cover', borderRadius: 8, marginBottom: 12 }} />}
+      <div className="row-actions">
+        <button type="button" className="btn" onClick={() => setOpen(true)}>{image ? 'Change fallback image' : 'Choose fallback image'}</button>
+        {image && <button type="button" className="btn ghost" onClick={() => setImage('')}>Remove image</button>}
+      </div>
+      <ImagePicker open={open} unsplashEnabled={unsplashEnabled} onClose={() => setOpen(false)} onSelect={(picked) => { setImage(picked.src); setOpen(false); }} />
+    </div>
+  );
+}

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/components/EventPage.astro

@@ -9,6 +9,7 @@ import { addToCalendarLinks, eventTimeZone, formatOccurrence, safeColor, type Oc
 import { describeRepeat } from '../lib/calendar/rrule';
 import { eventCardHtml, safeHref } from '../lib/calendar/cards';
 import { siteLocale } from '../lib/dates';
+import { eventImage } from '../lib/calendar/images';
 import { directionsUrl, mapAttribution, MAP_HEIGHT, MAP_WIDTH } from '../lib/maps/service';
 
 interface Props {
@@ -24,6 +25,7 @@ interface Props {
   rsvp?: { going: number; left: number | null; maxSeats: number; error: string; open: boolean; formHtml?: string; fieldsHtml?: string; values?: { name: string; email: string; seats: string } } | null;
 }
 const { event: e, occurrence: o, settings, calendars, html, upcoming, origin, preview = false, rsvp = null } = Astro.props;
+const image = eventImage(e, settings);
 const tz = eventTimeZone(e, settings);
 const locale = siteLocale(settings);
 const f = formatOccurrence(o, tz, locale);
@@ -61,8 +63,8 @@ const online = /zoom\.us|meet\.google|teams\.microsoft|webex|whereby|jit\.si/i.t
 
 <article class={`pc-ev-page${e.cancelled ? ' is-cancelled' : ''}`}>
   {preview && <p class="pc-ev-preview">Preview — only you can see this {e.status === 'published' ? 'version' : 'draft'}.</p>}
-  {e.cover && (
-    <figure class="pc-ev-hero"><img src={e.cover} alt={e.coverAlt} /></figure>
+  {image.src && (
+    <figure class="pc-ev-hero"><img src={image.src} alt={image.alt} /></figure>
   )}
   <div class="pc-ev-layout">
     <div class="pc-ev-main">