PROD-2306: clearer message for items referencing a deleted linked list

[5PK]

Root cause

When a content item references a linked list / linked container that has been deleted in the source, pushing the item fails and the CLI surfaces the Management API's response verbatim, e.g.:

Cannot create this item winnersgallery_linkcard_linke909a7 does not exist

The linked list isn't truly "nonexistent" — it was deleted. The pull prunes the deleted container's file locally (see download-containers.ts, which unlinks containers no longer returned by the source), and the CLI correctly refuses to recreate a deleted container on the target — so the target create fails. The does not exist text comes from the server, not our code, and it misleads triagers into thinking the reference name was never valid.

What changed

Scope is message clarity only.

• New util src/lib/pushers/content-pusher/util/detect-deleted-linked-list-references.ts:
  • collectAllReferenceNames(fields) — walks a content item's fields and gathers every linked-list/container referencename/referenceName.
  • findDeletedLinkedListReferences(fields, liveSourceContainerRefNames) — returns the referenced names absent from the live source containers (i.e. deleted).
  • buildDeletedLinkedListMessage(...) — builds the clear, actionable message and appends the original server error for triage context.
• content-batch-processor.ts:
  • Lazily builds (and caches) the set of container reference names still present in the source, read from the source containers/ folder.
  • When a content item fails, clarifyFailedItemError replaces the surfaced error with:
    Content item '<item>' references a deleted linked list '<name>' — clear the stale reference in the source or restore the list. (original error: ...)
• Focused unit test added for the new util.

Detection approach + limitation

Proactive, not string-matching the server text. A referenced linked list is treated as deleted-not-missing when its reference name is absent from the live source containers (the pull removes deleted containers' files, so absence is the deleted signal). This is applied at the failure-surfacing point: only failed items are re-messaged, and only when we can positively identify a deleted reference — otherwise the original error is preserved untouched.

Limitations:

• If containers were never pulled at all (e.g. containers out of scope for the run), the live set is empty and clarification is skipped, to avoid falsely reporting every reference as deleted.
• Detection keys on the reference being absent from the pulled source containers. It does not distinguish "deleted from source" from "reference name that never existed"; both surface as a deleted/stale linked-list reference, which is the actionable framing either way.

Deferred (out of scope — needs a product decision)

Graceful degradation — skipping/emptying the dangling linked-list field and creating the item anyway — is intentionally not implemented here. It changes what data lands on the target and should be a deliberate product decision. Tracking for follow-up on the ticket.

🤖 Generated with Claude Code