[5PK]

Combines #252 and #253 into one PR for the 1.3.0 beta, adds list order sync (PROD-2992) and the fixes from #255 (PROD-3042, PROD-3043), and bumps the version to 1.3.0-beta.0. Each branch is merged in as-is (no rewritten commits), so their own descriptions and reviews still apply. It's a minor version because --syncDeletes is a new feature.

What's in it

• Add --syncDeletes: delete on the target what was deleted in the source #252 --syncDeletes: an opt-in final phase for sync / push / reverse-sync. It deletes on the target what was deleted in the source since the last sync, for all eight entity types, in dependency order.
  • Only entities reached through a mapping are considered.
  • Each candidate is decided as delete, conflict, blocked, unmap or keep.
  • Content and page deletes are confirmed against the source API.
  • There's a mass-delete guard (--allowMassDeletes lifts it).
  • The flag is refused with --pages / --containers / --models / --models-with-deps, and it's never read from .env.
  • Planned deletes show in --preflight and --jsonSummary.
• PROD-3025, PROD-3076: push linked content in dependency order, two-pass for reference cycles #253 PROD-3025, linked content in dependency levels: linked items are pushed in dependency levels, leaves first, one batch per level. Before, they went as one batch, so in a chain like FeaturedPost → Post → Category, Post failed on an unresolved reference to Category, which was created later in the same batch. Works for chains of any depth.
• PROD-3025, PROD-3076: push linked content in dependency order, two-pass for reference cycles #253 PROD-3076, reference cycles: items that reference each other by content ID, or themselves, used to fail on every sync. They now get a two-pass push in the same run. Pass 1 creates them with the references into the cycle blanked. Pass 2 then sends them in full as updates, to the target items pass 1 created (trustSameRunMappings). Each item is counted and published once. A failed pass 2 is reported and pushed again on the next sync. The server accepts a required linked field saved blank, so required fields work too.
• PROD-3025, PROD-3076: push linked content in dependency order, two-pass for reference cycles #253 page titles: a page's source title is sent as-is, including an empty one (the Fetch API returns it as null), instead of falling back to the menu text or page name. The Management API's title is optional. This replaces Fixes from the sync permutation test: PROD-3042, PROD-3043, reverse-sync deletes #255's PROD-3043 fix, which did the same for dynamic pages only.
• PROD-2992 list order (new in this PR, on by default, no flag): after content and --syncDeletes, and before auto-publish, each synced content list is put in the source's item order on the target.
  • Only lists whose order differs from the target's pull are sent, or ones that gained an item this run. That includes a reorder-only change in the source, which never creates a new version.
  • It calls the Management API's list item-order endpoint (setContentListItemOrder, skipUnknownIds), which renumbers the staging and live list in place. No new versions, so nothing to publish.
  • Target-only items stay after the synced ones.
  • A scoped run orders only its lists, but sends every mapped item of those lists.
  • Preflight shows a List order phase, and --jsonSummary a listOrder phase. Skipped IDs are warnings; API errors are failures.
• Fixes from the sync permutation test: PROD-3042, PROD-3043, reverse-sync deletes #255, fixes from the two-direction sync permutation test:
  • PROD-3043: a dynamic page's empty title stays empty. Superseded in the merge by PROD-3025, PROD-3076: push linked content in dependency order, two-pass for reference cycles #253's version, which covers every page; PROD-3043's static-page test now expects the same.
  • PROD-3042: a page save realigns the requires-approval setting of its components' containers and bumps their modified date. After the page push, those containers' mappings now take the new date, so the next run doesn't report false "target changed" conflicts. Containers changed on the target before the run keep their conflict.
  • PROD-2992: a test for --syncDeletes on reverse-sync, and a reverse switch on the sync harness.
• Target-only content edits are conflicts (behaviour change): an item edited on the target since the last sync, with the source unchanged, used to be skipped as "up to date", even with --overwrite, and the target silently kept a version the source never had. It's now reported as a conflict and skipped, or replaced with the source under --overwrite, the same as pages, models and containers already did. Mappings with no recorded target version (older mapping files) are left alone. Syncs that passed before can now report conflicts where someone edited the target directly; --overwrite gives the old outcome plus the source's values. Assets and galleries now follow the same rule: assets overwrote a target-only edit without --overwrite, and galleries had the checks crossed (a both-sides edit was overwritten, a source-only change never synced, and --overwrite updated even unchanged galleries). Both now also log the conflict in a real run, not only in preflight. Templates, URL redirections and list order record no last-synced state, so they still let the source win; that's PROD-3078.
• verify: a link to an item deleted on both sides (by --syncDeletes, which also drops the mapping) now compares equal instead of unmapped:<id> against the target ID.
• CI: live sync test on throwaway instances, gating promotion to latest #251 CI sync permutation test is on main (with a reference-cycle fixture: A ↔ B and a self-reference through a required linked field, checked after the first sync by cycles). This branch changes it:
  • It runs only for a release, and gates the publish. It leases two instances and runs 10 to 15 minutes, so it no longer runs on PRs or nightly. A v* tag push checks the tag against package.json, runs the test on the tag's build, and publishes to npm under beta only if it passed. The promote job no longer looks up a test run, since every version published from now on has passed. Run it by hand on a branch with gh workflow run sync-permutation.yml --ref <branch> -f tier=beta.
  • The harness grades correctly. Every sync and preflight passes --syncDeletes. When a sync keeps edits the harness made on purpose (a conflict, drift), a resolve step settles them with --overwrite before verify and the no-op check. The conflict and drift checks need their own item reported. Verify and the no-op check retry up to three times 90s apart, for Fetch API lag after edits that create no version (list reorders, field renames). field-rename only renames optional fields; renaming a required one makes the server drop every item's value.

SDK

Builds against @agility/management-sdk 0.2.0-beta.3, locked in package-lock.json. Its integrity hash matches npm. That release has:

• urlRedirectionMethods.deleteUrlRedirections, which --syncDeletes uses for URL redirections;
• contentMethods.setContentListItemOrder, the new list item-order endpoint (in production), which the list order phase uses.

Checked on the combined branch

• npm run build, tsc and eslint (no errors) pass.
• Full Jest suite: 141 suites, 2,683 tests pass, including the list-order tests, Fixes from the sync permutation test: PROD-3042, PROD-3043, reverse-sync deletes #255's tests, PROD-3025, PROD-3076: push linked content in dependency order, two-pass for reference cycles #253's level, cycle and title tests, and the target-only conflict tests for content, assets and galleries.

Sync permutation check

A local quick-tier run of this branch (fresh dev instances, rounds in both directions, the cycle fixture, list order, --syncDeletes, and the harness changes above) passed every check, 17 of 17. Each round's verify matched and each no-op preflight planned nothing, first try. The PR no longer runs the test automatically; the tag push will.

The 4 image fields in the dev blog template that pointed at another instance's CDN referenced media that no longer existed. They now use an Agility logo, and the pool's stale copies were cycled out.

Before promoting to latest

• Add --syncDeletes: delete on the target what was deleted in the source #252's open checks are best run on this beta against a clone pair, with --preflight first:
  • what reading a deleted item returns;
  • deleting published items;
  • locale side effects;
  • the redirections DELETE endpoint in the target environment;
  • server refusals for models and templates that are still in use.

After merging: push the v1.3.0-beta.0 tag on main. The publish workflow runs the sync permutation test on it and, if it passes, publishes under beta. Then #252 and #253 can be closed as merged through here (#251 is already merged).

🤖 Generated with Claude Code